michael@0: /* michael@0: * ==================================================================== michael@0: * Licensed to the Apache Software Foundation (ASF) under one michael@0: * or more contributor license agreements. See the NOTICE file michael@0: * distributed with this work for additional information michael@0: * regarding copyright ownership. The ASF licenses this file michael@0: * to you under the Apache License, Version 2.0 (the michael@0: * "License"); you may not use this file except in compliance michael@0: * with the License. You may obtain a copy of the License at michael@0: * michael@0: * http://www.apache.org/licenses/LICENSE-2.0 michael@0: * michael@0: * Unless required by applicable law or agreed to in writing, michael@0: * software distributed under the License is distributed on an michael@0: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY michael@0: * KIND, either express or implied. See the License for the michael@0: * specific language governing permissions and limitations michael@0: * under the License. michael@0: * ==================================================================== michael@0: * michael@0: * This software consists of voluntary contributions made by many michael@0: * individuals on behalf of the Apache Software Foundation. For more michael@0: * information on the Apache Software Foundation, please see michael@0: * . michael@0: * michael@0: */ michael@0: michael@0: package ch.boye.httpclientandroidlib.impl.client; michael@0: michael@0: import ch.boye.httpclientandroidlib.annotation.NotThreadSafe; michael@0: michael@0: import ch.boye.httpclientandroidlib.params.HttpParams; michael@0: import ch.boye.httpclientandroidlib.params.AbstractHttpParams; michael@0: michael@0: /** michael@0: * Represents a stack of parameter collections. michael@0: * When retrieving a parameter, the stack is searched in a fixed order michael@0: * and the first match returned. Setting parameters via the stack is michael@0: * not supported. To minimize overhead, the stack has a fixed size and michael@0: * does not maintain an internal array. michael@0: * The supported stack entries, sorted by increasing priority, are: michael@0: *
    michael@0: *
  1. Application parameters: michael@0: * expected to be the same for all clients used by an application. michael@0: * These provide "global", that is application-wide, defaults. michael@0: *
    2. michael@0: *
  2. Client parameters: michael@0: * specific to an instance of michael@0: * {@link ch.boye.httpclientandroidlib.client.HttpClient HttpClient}. michael@0: * These provide client specific defaults. michael@0: *
    3. michael@0: *
  3. Request parameters: michael@0: * specific to a single request execution. michael@0: * For overriding client and global defaults. michael@0: *
    4. michael@0: *
  4. Override parameters: michael@0: * specific to an instance of michael@0: * {@link ch.boye.httpclientandroidlib.client.HttpClient HttpClient}. michael@0: * These can be used to set parameters that cannot be overridden michael@0: * on a per-request basis. michael@0: *
    5. michael@0: *
michael@0: * Each stack entry may be null. That is preferable over michael@0: * an empty params collection, since it avoids searching the empty collection michael@0: * when looking up parameters. michael@0: * michael@0: * michael@0: * michael@0: * @since 4.0 michael@0: */ michael@0: @NotThreadSafe michael@0: public class ClientParamsStack extends AbstractHttpParams { michael@0: michael@0: /** The application parameter collection, or null. */ michael@0: protected final HttpParams applicationParams; michael@0: michael@0: /** The client parameter collection, or null. */ michael@0: protected final HttpParams clientParams; michael@0: michael@0: /** The request parameter collection, or null. */ michael@0: protected final HttpParams requestParams; michael@0: michael@0: /** The override parameter collection, or null. */ michael@0: protected final HttpParams overrideParams; michael@0: michael@0: michael@0: /** michael@0: * Creates a new parameter stack from elements. michael@0: * The arguments will be stored as-is, there is no copying to michael@0: * prevent modification. michael@0: * michael@0: * @param aparams application parameters, or null michael@0: * @param cparams client parameters, or null michael@0: * @param rparams request parameters, or null michael@0: * @param oparams override parameters, or null michael@0: */ michael@0: public ClientParamsStack(HttpParams aparams, HttpParams cparams, michael@0: HttpParams rparams, HttpParams oparams) { michael@0: applicationParams = aparams; michael@0: clientParams = cparams; michael@0: requestParams = rparams; michael@0: overrideParams = oparams; michael@0: } michael@0: michael@0: michael@0: /** michael@0: * Creates a copy of a parameter stack. michael@0: * The new stack will have the exact same entries as the argument stack. michael@0: * There is no copying of parameters. michael@0: * michael@0: * @param stack the stack to copy michael@0: */ michael@0: public ClientParamsStack(ClientParamsStack stack) { michael@0: this(stack.getApplicationParams(), michael@0: stack.getClientParams(), michael@0: stack.getRequestParams(), michael@0: stack.getOverrideParams()); michael@0: } michael@0: michael@0: michael@0: /** michael@0: * Creates a modified copy of a parameter stack. michael@0: * The new stack will contain the explicitly passed elements. michael@0: * For elements where the explicit argument is null, michael@0: * the corresponding element from the argument stack is used. michael@0: * There is no copying of parameters. michael@0: * michael@0: * @param stack the stack to modify michael@0: * @param aparams application parameters, or null michael@0: * @param cparams client parameters, or null michael@0: * @param rparams request parameters, or null michael@0: * @param oparams override parameters, or null michael@0: */ michael@0: public ClientParamsStack(ClientParamsStack stack, michael@0: HttpParams aparams, HttpParams cparams, michael@0: HttpParams rparams, HttpParams oparams) { michael@0: this((aparams != null) ? aparams : stack.getApplicationParams(), michael@0: (cparams != null) ? cparams : stack.getClientParams(), michael@0: (rparams != null) ? rparams : stack.getRequestParams(), michael@0: (oparams != null) ? oparams : stack.getOverrideParams()); michael@0: } michael@0: michael@0: michael@0: /** michael@0: * Obtains the application parameters of this stack. michael@0: * michael@0: * @return the application parameters, or null michael@0: */ michael@0: public final HttpParams getApplicationParams() { michael@0: return applicationParams; michael@0: } michael@0: michael@0: /** michael@0: * Obtains the client parameters of this stack. michael@0: * michael@0: * @return the client parameters, or null michael@0: */ michael@0: public final HttpParams getClientParams() { michael@0: return clientParams; michael@0: } michael@0: michael@0: /** michael@0: * Obtains the request parameters of this stack. michael@0: * michael@0: * @return the request parameters, or null michael@0: */ michael@0: public final HttpParams getRequestParams() { michael@0: return requestParams; michael@0: } michael@0: michael@0: /** michael@0: * Obtains the override parameters of this stack. michael@0: * michael@0: * @return the override parameters, or null michael@0: */ michael@0: public final HttpParams getOverrideParams() { michael@0: return overrideParams; michael@0: } michael@0: michael@0: michael@0: /** michael@0: * Obtains a parameter from this stack. michael@0: * See class comment for search order. michael@0: * michael@0: * @param name the name of the parameter to obtain michael@0: * michael@0: * @return the highest-priority value for that parameter, or michael@0: * null if it is not set anywhere in this stack michael@0: */ michael@0: public Object getParameter(String name) { michael@0: if (name == null) { michael@0: throw new IllegalArgumentException michael@0: ("Parameter name must not be null."); michael@0: } michael@0: michael@0: Object result = null; michael@0: michael@0: if (overrideParams != null) { michael@0: result = overrideParams.getParameter(name); michael@0: } michael@0: if ((result == null) && (requestParams != null)) { michael@0: result = requestParams.getParameter(name); michael@0: } michael@0: if ((result == null) && (clientParams != null)) { michael@0: result = clientParams.getParameter(name); michael@0: } michael@0: if ((result == null) && (applicationParams != null)) { michael@0: result = applicationParams.getParameter(name); michael@0: } michael@0: return result; michael@0: } michael@0: michael@0: /** michael@0: * Does not set a parameter. michael@0: * Parameter stacks are read-only. It is possible, though discouraged, michael@0: * to access and modify specific stack entries. michael@0: * Derived classes may change this behavior. michael@0: * michael@0: * @param name ignored michael@0: * @param value ignored michael@0: * michael@0: * @return nothing michael@0: * michael@0: * @throws UnsupportedOperationException always michael@0: */ michael@0: public HttpParams setParameter(String name, Object value) michael@0: throws UnsupportedOperationException { michael@0: michael@0: throw new UnsupportedOperationException michael@0: ("Setting parameters in a stack is not supported."); michael@0: } michael@0: michael@0: michael@0: /** michael@0: * Does not remove a parameter. michael@0: * Parameter stacks are read-only. It is possible, though discouraged, michael@0: * to access and modify specific stack entries. michael@0: * Derived classes may change this behavior. michael@0: * michael@0: * @param name ignored michael@0: * michael@0: * @return nothing michael@0: * michael@0: * @throws UnsupportedOperationException always michael@0: */ michael@0: public boolean removeParameter(String name) { michael@0: throw new UnsupportedOperationException michael@0: ("Removing parameters in a stack is not supported."); michael@0: } michael@0: michael@0: michael@0: /** michael@0: * Does not copy parameters. michael@0: * Parameter stacks are lightweight objects, expected to be instantiated michael@0: * as needed and to be used only in a very specific context. On top of michael@0: * that, they are read-only. The typical copy operation to prevent michael@0: * accidental modification of parameters passed by the application to michael@0: * a framework object is therefore pointless and disabled. michael@0: * Create a new stack if you really need a copy. michael@0: *
michael@0: * Derived classes may change this behavior. michael@0: * michael@0: * @return this parameter stack michael@0: */ michael@0: public HttpParams copy() { michael@0: return this; michael@0: } michael@0: michael@0: michael@0: }