/*
 * $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;
    }


}