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.DefaultedHttpParams;
33 import org.apache.http.params.HttpParams;
34 import org.apache.http.util.Args;
35
36 /**
37 * Represents a stack of parameter collections.
38 * When retrieving a parameter, the stack is searched in a fixed order
39 * and the first match returned. Setting parameters via the stack is
40 * not supported. To minimize overhead, the stack has a fixed size and
41 * does not maintain an internal array.
42 * The supported stack entries, sorted by increasing priority, are:
43 * <ol>
44 * <li>Application parameters:
45 * expected to be the same for all clients used by an application.
46 * These provide "global", that is application-wide, defaults.
47 * </li>
48 * <li>Client parameters:
49 * specific to an instance of
50 * {@link org.apache.http.client.HttpClient HttpClient}.
51 * These provide client specific defaults.
52 * </li>
53 * <li>Request parameters:
54 * specific to a single request execution.
55 * For overriding client and global defaults.
56 * </li>
57 * <li>Override parameters:
58 * specific to an instance of
59 * {@link org.apache.http.client.HttpClient HttpClient}.
60 * These can be used to set parameters that cannot be overridden
61 * on a per-request basis.
62 * </li>
63 * </ol>
64 * Each stack entry may be <code>null</code>. That is preferable over
65 * an empty params collection, since it avoids searching the empty collection
66 * when looking up parameters.
67 *
68 * @since 4.0
69 *
70 * @deprecated (4.3) use {@link DefaultedHttpParams}
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 }