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  import org.apache.http.params.AbstractHttpParams;
32  import org.apache.http.params.HttpParams;
33  import org.apache.http.util.Args;
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   * @since 4.0
68   *
69   * @deprecated (4.3) use configuration classes provided 'org.apache.http.config'
70   *  and 'org.apache.http.client.config'
71   */
72  @NotThreadSafe
73  @Deprecated
74  public class ClientParamsStack extends AbstractHttpParams {
75  
76      /** The application parameter collection, or <code>null</code>. */
77      protected final HttpParams applicationParams;
78  
79      /** The client parameter collection, or <code>null</code>. */
80      protected final HttpParams clientParams;
81  
82      /** The request parameter collection, or <code>null</code>. */
83      protected final HttpParams requestParams;
84  
85      /** The override parameter collection, or <code>null</code>. */
86      protected final HttpParams overrideParams;
87  
88  
89      /**
90       * Creates a new parameter stack from elements.
91       * The arguments will be stored as-is, there is no copying to
92       * prevent modification.
93       *
94       * @param aparams   application parameters, or <code>null</code>
95       * @param cparams   client parameters, or <code>null</code>
96       * @param rparams   request parameters, or <code>null</code>
97       * @param oparams   override parameters, or <code>null</code>
98       */
99      public ClientParamsStack(final HttpParams aparams, final HttpParams cparams,
100                              final HttpParams rparams, final HttpParams oparams) {
101         applicationParams = aparams;
102         clientParams      = cparams;
103         requestParams     = rparams;
104         overrideParams    = oparams;
105     }
106 
107 
108     /**
109      * Creates a copy of a parameter stack.
110      * The new stack will have the exact same entries as the argument stack.
111      * There is no copying of parameters.
112      *
113      * @param stack     the stack to copy
114      */
115     public ClientParamsStack(final ClientParamsStack stack) {
116         this(stack.getApplicationParams(),
117              stack.getClientParams(),
118              stack.getRequestParams(),
119              stack.getOverrideParams());
120     }
121 
122 
123     /**
124      * Creates a modified copy of a parameter stack.
125      * The new stack will contain the explicitly passed elements.
126      * For elements where the explicit argument is <code>null</code>,
127      * the corresponding element from the argument stack is used.
128      * There is no copying of parameters.
129      *
130      * @param stack     the stack to modify
131      * @param aparams   application parameters, or <code>null</code>
132      * @param cparams   client parameters, or <code>null</code>
133      * @param rparams   request parameters, or <code>null</code>
134      * @param oparams   override parameters, or <code>null</code>
135      */
136     public ClientParamsStack(final ClientParamsStack stack,
137                              final HttpParams aparams, final HttpParams cparams,
138                              final HttpParams rparams, final HttpParams oparams) {
139         this((aparams != null) ? aparams : stack.getApplicationParams(),
140              (cparams != null) ? cparams : stack.getClientParams(),
141              (rparams != null) ? rparams : stack.getRequestParams(),
142              (oparams != null) ? oparams : stack.getOverrideParams());
143     }
144 
145 
146     /**
147      * Obtains the application parameters of this stack.
148      *
149      * @return  the application parameters, or <code>null</code>
150      */
151     public final HttpParams getApplicationParams() {
152         return applicationParams;
153     }
154 
155     /**
156      * Obtains the client parameters of this stack.
157      *
158      * @return  the client parameters, or <code>null</code>
159      */
160     public final HttpParams getClientParams() {
161         return clientParams;
162     }
163 
164     /**
165      * Obtains the request parameters of this stack.
166      *
167      * @return  the request parameters, or <code>null</code>
168      */
169     public final HttpParams getRequestParams() {
170         return requestParams;
171     }
172 
173     /**
174      * Obtains the override parameters of this stack.
175      *
176      * @return  the override parameters, or <code>null</code>
177      */
178     public final HttpParams getOverrideParams() {
179         return overrideParams;
180     }
181 
182 
183     /**
184      * Obtains a parameter from this stack.
185      * See class comment for search order.
186      *
187      * @param name      the name of the parameter to obtain
188      *
189      * @return  the highest-priority value for that parameter, or
190      *          <code>null</code> if it is not set anywhere in this stack
191      */
192     public Object getParameter(final String name) {
193         Args.notNull(name, "Parameter name");
194 
195         Object result = null;
196 
197         if (overrideParams != null) {
198             result = overrideParams.getParameter(name);
199         }
200         if ((result == null) && (requestParams != null)) {
201             result = requestParams.getParameter(name);
202         }
203         if ((result == null) && (clientParams != null)) {
204             result = clientParams.getParameter(name);
205         }
206         if ((result == null) && (applicationParams != null)) {
207             result = applicationParams.getParameter(name);
208         }
209         return result;
210     }
211 
212     /**
213      * Does <i>not</i> set a parameter.
214      * Parameter stacks are read-only. It is possible, though discouraged,
215      * to access and modify specific stack entries.
216      * Derived classes may change this behavior.
217      *
218      * @param name      ignored
219      * @param value     ignored
220      *
221      * @return  nothing
222      *
223      * @throws UnsupportedOperationException    always
224      */
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     public boolean removeParameter(final String name) {
246         throw new UnsupportedOperationException
247         ("Removing parameters in a stack is not supported.");
248     }
249 
250 
251     /**
252      * Does <i>not</i> copy parameters.
253      * Parameter stacks are lightweight objects, expected to be instantiated
254      * as needed and to be used only in a very specific context. On top of
255      * that, they are read-only. The typical copy operation to prevent
256      * accidental modification of parameters passed by the application to
257      * a framework object is therefore pointless and disabled.
258      * Create a new stack if you really need a copy.
259      * <br/>
260      * Derived classes may change this behavior.
261      *
262      * @return <code>this</code> parameter stack
263      */
264     public HttpParams copy() {
265         return this;
266     }
267 
268 
269 }