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