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.annotation.NotThreadSafe;
31  
32  import org.apache.http.params.HttpParams;
33  import org.apache.http.params.AbstractHttpParams;
34  
35  /**
36   * Represents a stack of parameter collections.
37   * When retrieving a parameter, the stack is searched in a fixed order
38   * and the first match returned. Setting parameters via the stack is
39   * not supported. To minimize overhead, the stack has a fixed size and
40   * does not maintain an internal array.
41   * The supported stack entries, sorted by increasing priority, are:
42   * <ol>
43   * <li>Application parameters:
44   *     expected to be the same for all clients used by an application.
45   *     These provide "global", that is application-wide, defaults.
46   *     </li>
47   * <li>Client parameters:
48   *     specific to an instance of
49   *     {@link org.apache.http.client.HttpClient HttpClient}.
50   *     These provide client specific defaults.
51   *     </li>
52   * <li>Request parameters:
53   *     specific to a single request execution.
54   *     For overriding client and global defaults.
55   *     </li>
56   * <li>Override parameters:
57   *     specific to an instance of
58   *     {@link org.apache.http.client.HttpClient HttpClient}.
59   *     These can be used to set parameters that cannot be overridden
60   *     on a per-request basis.
61   *     </li>
62   * </ol>
63   * Each stack entry may be <code>null</code>. That is preferable over
64   * an empty params collection, since it avoids searching the empty collection
65   * when looking up parameters.
66   *
67   *
68   *
69   * @since 4.0
70   */
71  @NotThreadSafe
72  public class ClientParamsStack extends AbstractHttpParams {
73  
74      /** The application parameter collection, or <code>null</code>. */
75      protected final HttpParams applicationParams;
76  
77      /** The client parameter collection, or <code>null</code>. */
78      protected final HttpParams clientParams;
79  
80      /** The request parameter collection, or <code>null</code>. */
81      protected final HttpParams requestParams;
82  
83      /** The override parameter collection, or <code>null</code>. */
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</code>
93       * @param cparams   client parameters, or <code>null</code>
94       * @param rparams   request parameters, or <code>null</code>
95       * @param oparams   override parameters, or <code>null</code>
96       */
97      public ClientParamsStack(HttpParams aparams, HttpParams cparams,
98                               HttpParams rparams, 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(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</code>,
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</code>
130      * @param cparams   client parameters, or <code>null</code>
131      * @param rparams   request parameters, or <code>null</code>
132      * @param oparams   override parameters, or <code>null</code>
133      */
134     public ClientParamsStack(ClientParamsStack stack,
135                              HttpParams aparams, HttpParams cparams,
136                              HttpParams rparams, 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</code>
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</code>
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</code>
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</code>
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</code> if it is not set anywhere in this stack
189      */
190     public Object getParameter(String name) {
191         if (name == null) {
192             throw new IllegalArgumentException
193                 ("Parameter name must not be null.");
194         }
195 
196         Object result = null;
197 
198         if (overrideParams != null) {
199             result = overrideParams.getParameter(name);
200         }
201         if ((result == null) && (requestParams != null)) {
202             result = requestParams.getParameter(name);
203         }
204         if ((result == null) && (clientParams != null)) {
205             result = clientParams.getParameter(name);
206         }
207         if ((result == null) && (applicationParams != null)) {
208             result = applicationParams.getParameter(name);
209         }
210         return result;
211     }
212 
213     /**
214      * Does <i>not</i> set a parameter.
215      * Parameter stacks are read-only. It is possible, though discouraged,
216      * to access and modify specific stack entries.
217      * Derived classes may change this behavior.
218      *
219      * @param name      ignored
220      * @param value     ignored
221      *
222      * @return  nothing
223      *
224      * @throws UnsupportedOperationException    always
225      */
226     public HttpParams setParameter(String name, Object value)
227         throws UnsupportedOperationException {
228 
229         throw new UnsupportedOperationException
230             ("Setting parameters in a stack is not supported.");
231     }
232 
233 
234     /**
235      * Does <i>not</i> remove a parameter.
236      * Parameter stacks are read-only. It is possible, though discouraged,
237      * to access and modify specific stack entries.
238      * Derived classes may change this behavior.
239      *
240      * @param name      ignored
241      *
242      * @return  nothing
243      *
244      * @throws UnsupportedOperationException    always
245      */
246     public boolean removeParameter(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      * <br/>
261      * Derived classes may change this behavior.
262      *
263      * @return <code>this</code> parameter stack
264      */
265     public HttpParams copy() {
266         return this;
267     }
268 
269 
270 }