View Javadoc
1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http.impl.client;
29  
30  import org.apache.http.params.AbstractHttpParams;
31  import org.apache.http.params.HttpParams;
32  import org.apache.http.util.Args;
33  
34  /**
35   * Represents a stack of parameter collections.
36   * When retrieving a parameter, the stack is searched in a fixed order
37   * and the first match returned. Setting parameters via the stack is
38   * not supported. To minimize overhead, the stack has a fixed size and
39   * does not maintain an internal array.
40   * The supported stack entries, sorted by increasing priority, are:
41   * <ol>
42   * <li>Application parameters:
43   *     expected to be the same for all clients used by an application.
44   *     These provide "global", that is application-wide, defaults.
45   *     </li>
46   * <li>Client parameters:
47   *     specific to an instance of
48   *     {@link org.apache.http.client.HttpClient HttpClient}.
49   *     These provide client specific defaults.
50   *     </li>
51   * <li>Request parameters:
52   *     specific to a single request execution.
53   *     For overriding client and global defaults.
54   *     </li>
55   * <li>Override parameters:
56   *     specific to an instance of
57   *     {@link org.apache.http.client.HttpClient HttpClient}.
58   *     These can be used to set parameters that cannot be overridden
59   *     on a per-request basis.
60   *     </li>
61   * </ol>
62   * Each stack entry may be {@code null}. That is preferable over
63   * an empty params collection, since it avoids searching the empty collection
64   * when looking up parameters.
65   *
66   * @since 4.0
67   *
68   * @deprecated (4.3) use configuration classes provided 'org.apache.http.config'
69   *  and 'org.apache.http.client.config'
70   */
71  @Deprecated
72  public class ClientParamsStack extends AbstractHttpParams {
73  
74      /** The application parameter collection, or {@code null}. */
75      protected final HttpParams applicationParams;
76  
77      /** The client parameter collection, or {@code null}. */
78      protected final HttpParams clientParams;
79  
80      /** The request parameter collection, or {@code null}. */
81      protected final HttpParams requestParams;
82  
83      /** The override parameter collection, or {@code null}. */
84      protected final HttpParams overrideParams;
85  
86  
87      /**
88       * Creates a new parameter stack from elements.
89       * The arguments will be stored as-is, there is no copying to
90       * prevent modification.
91       *
92       * @param aparams   application parameters, or {@code null}
93       * @param cparams   client parameters, or {@code null}
94       * @param rparams   request parameters, or {@code null}
95       * @param oparams   override parameters, or {@code null}
96       */
97      public ClientParamsStack(final HttpParams aparams, final HttpParams cparams,
98                               final HttpParams rparams, final HttpParams oparams) {
99          applicationParams = aparams;
100         clientParams      = cparams;
101         requestParams     = rparams;
102         overrideParams    = oparams;
103     }
104 
105 
106     /**
107      * Creates a copy of a parameter stack.
108      * The new stack will have the exact same entries as the argument stack.
109      * There is no copying of parameters.
110      *
111      * @param stack     the stack to copy
112      */
113     public ClientParamsStack(final ClientParamsStack stack) {
114         this(stack.getApplicationParams(),
115              stack.getClientParams(),
116              stack.getRequestParams(),
117              stack.getOverrideParams());
118     }
119 
120 
121     /**
122      * Creates a modified copy of a parameter stack.
123      * The new stack will contain the explicitly passed elements.
124      * For elements where the explicit argument is {@code null},
125      * the corresponding element from the argument stack is used.
126      * There is no copying of parameters.
127      *
128      * @param stack     the stack to modify
129      * @param aparams   application parameters, or {@code null}
130      * @param cparams   client parameters, or {@code null}
131      * @param rparams   request parameters, or {@code null}
132      * @param oparams   override parameters, or {@code null}
133      */
134     public ClientParamsStack(final ClientParamsStack stack,
135                              final HttpParams aparams, final HttpParams cparams,
136                              final HttpParams rparams, final HttpParams oparams) {
137         this((aparams != null) ? aparams : stack.getApplicationParams(),
138              (cparams != null) ? cparams : stack.getClientParams(),
139              (rparams != null) ? rparams : stack.getRequestParams(),
140              (oparams != null) ? oparams : stack.getOverrideParams());
141     }
142 
143 
144     /**
145      * Obtains the application parameters of this stack.
146      *
147      * @return  the application parameters, or {@code null}
148      */
149     public final HttpParams getApplicationParams() {
150         return applicationParams;
151     }
152 
153     /**
154      * Obtains the client parameters of this stack.
155      *
156      * @return  the client parameters, or {@code null}
157      */
158     public final HttpParams getClientParams() {
159         return clientParams;
160     }
161 
162     /**
163      * Obtains the request parameters of this stack.
164      *
165      * @return  the request parameters, or {@code null}
166      */
167     public final HttpParams getRequestParams() {
168         return requestParams;
169     }
170 
171     /**
172      * Obtains the override parameters of this stack.
173      *
174      * @return  the override parameters, or {@code null}
175      */
176     public final HttpParams getOverrideParams() {
177         return overrideParams;
178     }
179 
180 
181     /**
182      * Obtains a parameter from this stack.
183      * See class comment for search order.
184      *
185      * @param name      the name of the parameter to obtain
186      *
187      * @return  the highest-priority value for that parameter, or
188      *          {@code null} if it is not set anywhere in this stack
189      */
190     @Override
191     public Object getParameter(final String name) {
192         Args.notNull(name, "Parameter name");
193 
194         Object result = null;
195 
196         if (overrideParams != null) {
197             result = overrideParams.getParameter(name);
198         }
199         if ((result == null) && (requestParams != null)) {
200             result = requestParams.getParameter(name);
201         }
202         if ((result == null) && (clientParams != null)) {
203             result = clientParams.getParameter(name);
204         }
205         if ((result == null) && (applicationParams != null)) {
206             result = applicationParams.getParameter(name);
207         }
208         return result;
209     }
210 
211     /**
212      * Does <i>not</i> set a parameter.
213      * Parameter stacks are read-only. It is possible, though discouraged,
214      * to access and modify specific stack entries.
215      * Derived classes may change this behavior.
216      *
217      * @param name      ignored
218      * @param value     ignored
219      *
220      * @return  nothing
221      *
222      * @throws UnsupportedOperationException    always
223      */
224     @Override
225     public HttpParams setParameter(final String name, final Object value)
226         throws UnsupportedOperationException {
227 
228         throw new UnsupportedOperationException
229             ("Setting parameters in a stack is not supported.");
230     }
231 
232 
233     /**
234      * Does <i>not</i> remove a parameter.
235      * Parameter stacks are read-only. It is possible, though discouraged,
236      * to access and modify specific stack entries.
237      * Derived classes may change this behavior.
238      *
239      * @param name      ignored
240      *
241      * @return  nothing
242      *
243      * @throws UnsupportedOperationException    always
244      */
245     @Override
246     public boolean removeParameter(final String name) {
247         throw new UnsupportedOperationException
248         ("Removing parameters in a stack is not supported.");
249     }
250 
251 
252     /**
253      * Does <i>not</i> copy parameters.
254      * Parameter stacks are lightweight objects, expected to be instantiated
255      * as needed and to be used only in a very specific context. On top of
256      * that, they are read-only. The typical copy operation to prevent
257      * accidental modification of parameters passed by the application to
258      * a framework object is therefore pointless and disabled.
259      * Create a new stack if you really need a copy.
260      * <p>
261      * Derived classes may change this behavior.
262      * </p>
263      *
264      * @return {@code this} parameter stack
265      */
266     @Override
267     public HttpParams copy() {
268         return this;
269     }
270 
271 
272 }