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 ClientParamsStacklientParamsStack.html#ClientParamsStack">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 ClientParamsStacklientParamsStack.html#ClientParamsStack">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 }