Home | History | Annotate | Download | only in client
      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 
     32 package org.apache.http.impl.client;
     33 
     34 
     35 import org.apache.commons.logging.Log;
     36 import org.apache.commons.logging.LogFactory;
     37 import org.apache.http.params.HttpParams;
     38 import 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  *
     78  * @deprecated Please use {@link java.net.URL#openConnection} instead.
     79  *     Please visit <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html">this webpage</a>
     80  *     for further details.
     81  */
     82 @Deprecated
     83 public class ClientParamsStack extends AbstractHttpParams {
     84 
     85     private final Log log = LogFactory.getLog(getClass());
     86 
     87     /** The application parameter collection, or <code>null</code>. */
     88     protected final HttpParams applicationParams;
     89 
     90     /** The client parameter collection, or <code>null</code>. */
     91     protected final HttpParams clientParams;
     92 
     93     /** The request parameter collection, or <code>null</code>. */
     94     protected final HttpParams requestParams;
     95 
     96     /** The override parameter collection, or <code>null</code>. */
     97     protected final HttpParams overrideParams;
     98 
     99 
    100     /**
    101      * Creates a new parameter stack from elements.
    102      * The arguments will be stored as-is, there is no copying to
    103      * prevent modification.
    104      *
    105      * @param aparams   application parameters, or <code>null</code>
    106      * @param cparams   client parameters, or <code>null</code>
    107      * @param rparams   request parameters, or <code>null</code>
    108      * @param oparams   override parameters, or <code>null</code>
    109      */
    110     public ClientParamsStack(HttpParams aparams, HttpParams cparams,
    111                              HttpParams rparams, HttpParams oparams) {
    112         applicationParams = aparams;
    113         clientParams      = cparams;
    114         requestParams     = rparams;
    115         overrideParams    = oparams;
    116     }
    117 
    118 
    119     /**
    120      * Creates a copy of a parameter stack.
    121      * The new stack will have the exact same entries as the argument stack.
    122      * There is no copying of parameters.
    123      *
    124      * @param stack     the stack to copy
    125      */
    126     public ClientParamsStack(ClientParamsStack stack) {
    127         this(stack.getApplicationParams(),
    128              stack.getClientParams(),
    129              stack.getRequestParams(),
    130              stack.getOverrideParams());
    131     }
    132 
    133 
    134     /**
    135      * Creates a modified copy of a parameter stack.
    136      * The new stack will contain the explicitly passed elements.
    137      * For elements where the explicit argument is <code>null</code>,
    138      * the corresponding element from the argument stack is used.
    139      * There is no copying of parameters.
    140      *
    141      * @param stack     the stack to modify
    142      * @param aparams   application parameters, or <code>null</code>
    143      * @param cparams   client parameters, or <code>null</code>
    144      * @param rparams   request parameters, or <code>null</code>
    145      * @param oparams   override parameters, or <code>null</code>
    146      */
    147     public ClientParamsStack(ClientParamsStack stack,
    148                              HttpParams aparams, HttpParams cparams,
    149                              HttpParams rparams, HttpParams oparams) {
    150         this((aparams != null) ? aparams : stack.getApplicationParams(),
    151              (cparams != null) ? cparams : stack.getClientParams(),
    152              (rparams != null) ? rparams : stack.getRequestParams(),
    153              (oparams != null) ? oparams : stack.getOverrideParams());
    154     }
    155 
    156 
    157     /**
    158      * Obtains the application parameters of this stack.
    159      *
    160      * @return  the application parameters, or <code>null</code>
    161      */
    162     public final HttpParams getApplicationParams() {
    163         return applicationParams;
    164     }
    165 
    166     /**
    167      * Obtains the client parameters of this stack.
    168      *
    169      * @return  the client parameters, or <code>null</code>
    170      */
    171     public final HttpParams getClientParams() {
    172         return clientParams;
    173     }
    174 
    175     /**
    176      * Obtains the request parameters of this stack.
    177      *
    178      * @return  the request parameters, or <code>null</code>
    179      */
    180     public final HttpParams getRequestParams() {
    181         return requestParams;
    182     }
    183 
    184     /**
    185      * Obtains the override parameters of this stack.
    186      *
    187      * @return  the override parameters, or <code>null</code>
    188      */
    189     public final HttpParams getOverrideParams() {
    190         return overrideParams;
    191     }
    192 
    193 
    194     /**
    195      * Obtains a parameter from this stack.
    196      * See class comment for search order.
    197      *
    198      * @param name      the name of the parameter to obtain
    199      *
    200      * @return  the highest-priority value for that parameter, or
    201      *          <code>null</code> if it is not set anywhere in this stack
    202      */
    203     public Object getParameter(String name) {
    204         if (name == null) {
    205             throw new IllegalArgumentException
    206                 ("Parameter name must not be null.");
    207         }
    208 
    209         Object result = null;
    210 
    211         if (overrideParams != null) {
    212             result = overrideParams.getParameter(name);
    213         }
    214         if ((result == null) && (requestParams != null)) {
    215             result = requestParams.getParameter(name);
    216         }
    217         if ((result == null) && (clientParams != null)) {
    218             result = clientParams.getParameter(name);
    219         }
    220         if ((result == null) && (applicationParams != null)) {
    221             result = applicationParams.getParameter(name);
    222         }
    223         if (this.log.isDebugEnabled()) {
    224             this.log.debug("'" + name + "': " + result);
    225         }
    226 
    227         return result;
    228     }
    229 
    230     /**
    231      * Does <i>not</i> set a parameter.
    232      * Parameter stacks are read-only. It is possible, though discouraged,
    233      * to access and modify specific stack entries.
    234      * Derived classes may change this behavior.
    235      *
    236      * @param name      ignored
    237      * @param value     ignored
    238      *
    239      * @return  nothing
    240      *
    241      * @throws UnsupportedOperationException    always
    242      */
    243     public HttpParams setParameter(String name, Object value)
    244         throws UnsupportedOperationException {
    245 
    246         throw new UnsupportedOperationException
    247             ("Setting parameters in a stack is not supported.");
    248     }
    249 
    250 
    251     /**
    252      * Does <i>not</i> remove a parameter.
    253      * Parameter stacks are read-only. It is possible, though discouraged,
    254      * to access and modify specific stack entries.
    255      * Derived classes may change this behavior.
    256      *
    257      * @param name      ignored
    258      *
    259      * @return  nothing
    260      *
    261      * @throws UnsupportedOperationException    always
    262      */
    263     public boolean removeParameter(String name) {
    264         throw new UnsupportedOperationException
    265         ("Removing parameters in a stack is not supported.");
    266     }
    267 
    268 
    269     /**
    270      * Does <i>not</i> copy parameters.
    271      * Parameter stacks are lightweight objects, expected to be instantiated
    272      * as needed and to be used only in a very specific context. On top of
    273      * that, they are read-only. The typical copy operation to prevent
    274      * accidental modification of parameters passed by the application to
    275      * a framework object is therefore pointless and disabled.
    276      * Create a new stack if you really need a copy.
    277      * <br/>
    278      * Derived classes may change this behavior.
    279      *
    280      * @return <code>this</code> parameter stack
    281      */
    282     public HttpParams copy() {
    283         return this;
    284     }
    285 
    286 
    287 }
    288