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