1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/impl/client/ClientParamsStack.java Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,270 @@
1.4 +/*
1.5 + * ====================================================================
1.6 + * Licensed to the Apache Software Foundation (ASF) under one
1.7 + * or more contributor license agreements. See the NOTICE file
1.8 + * distributed with this work for additional information
1.9 + * regarding copyright ownership. The ASF licenses this file
1.10 + * to you under the Apache License, Version 2.0 (the
1.11 + * "License"); you may not use this file except in compliance
1.12 + * with the License. You may obtain a copy of the License at
1.13 + *
1.14 + * http://www.apache.org/licenses/LICENSE-2.0
1.15 + *
1.16 + * Unless required by applicable law or agreed to in writing,
1.17 + * software distributed under the License is distributed on an
1.18 + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1.19 + * KIND, either express or implied. See the License for the
1.20 + * specific language governing permissions and limitations
1.21 + * under the License.
1.22 + * ====================================================================
1.23 + *
1.24 + * This software consists of voluntary contributions made by many
1.25 + * individuals on behalf of the Apache Software Foundation. For more
1.26 + * information on the Apache Software Foundation, please see
1.27 + * <http://www.apache.org/>.
1.28 + *
1.29 + */
1.30 +
1.31 +package ch.boye.httpclientandroidlib.impl.client;
1.32 +
1.33 +import ch.boye.httpclientandroidlib.annotation.NotThreadSafe;
1.34 +
1.35 +import ch.boye.httpclientandroidlib.params.HttpParams;
1.36 +import ch.boye.httpclientandroidlib.params.AbstractHttpParams;
1.37 +
1.38 +/**
1.39 + * Represents a stack of parameter collections.
1.40 + * When retrieving a parameter, the stack is searched in a fixed order
1.41 + * and the first match returned. Setting parameters via the stack is
1.42 + * not supported. To minimize overhead, the stack has a fixed size and
1.43 + * does not maintain an internal array.
1.44 + * The supported stack entries, sorted by increasing priority, are:
1.45 + * <ol>
1.46 + * <li>Application parameters:
1.47 + * expected to be the same for all clients used by an application.
1.48 + * These provide "global", that is application-wide, defaults.
1.49 + * </li>
1.50 + * <li>Client parameters:
1.51 + * specific to an instance of
1.52 + * {@link ch.boye.httpclientandroidlib.client.HttpClient HttpClient}.
1.53 + * These provide client specific defaults.
1.54 + * </li>
1.55 + * <li>Request parameters:
1.56 + * specific to a single request execution.
1.57 + * For overriding client and global defaults.
1.58 + * </li>
1.59 + * <li>Override parameters:
1.60 + * specific to an instance of
1.61 + * {@link ch.boye.httpclientandroidlib.client.HttpClient HttpClient}.
1.62 + * These can be used to set parameters that cannot be overridden
1.63 + * on a per-request basis.
1.64 + * </li>
1.65 + * </ol>
1.66 + * Each stack entry may be <code>null</code>. That is preferable over
1.67 + * an empty params collection, since it avoids searching the empty collection
1.68 + * when looking up parameters.
1.69 + *
1.70 + *
1.71 + *
1.72 + * @since 4.0
1.73 + */
1.74 +@NotThreadSafe
1.75 +public class ClientParamsStack extends AbstractHttpParams {
1.76 +
1.77 + /** The application parameter collection, or <code>null</code>. */
1.78 + protected final HttpParams applicationParams;
1.79 +
1.80 + /** The client parameter collection, or <code>null</code>. */
1.81 + protected final HttpParams clientParams;
1.82 +
1.83 + /** The request parameter collection, or <code>null</code>. */
1.84 + protected final HttpParams requestParams;
1.85 +
1.86 + /** The override parameter collection, or <code>null</code>. */
1.87 + protected final HttpParams overrideParams;
1.88 +
1.89 +
1.90 + /**
1.91 + * Creates a new parameter stack from elements.
1.92 + * The arguments will be stored as-is, there is no copying to
1.93 + * prevent modification.
1.94 + *
1.95 + * @param aparams application parameters, or <code>null</code>
1.96 + * @param cparams client parameters, or <code>null</code>
1.97 + * @param rparams request parameters, or <code>null</code>
1.98 + * @param oparams override parameters, or <code>null</code>
1.99 + */
1.100 + public ClientParamsStack(HttpParams aparams, HttpParams cparams,
1.101 + HttpParams rparams, HttpParams oparams) {
1.102 + applicationParams = aparams;
1.103 + clientParams = cparams;
1.104 + requestParams = rparams;
1.105 + overrideParams = oparams;
1.106 + }
1.107 +
1.108 +
1.109 + /**
1.110 + * Creates a copy of a parameter stack.
1.111 + * The new stack will have the exact same entries as the argument stack.
1.112 + * There is no copying of parameters.
1.113 + *
1.114 + * @param stack the stack to copy
1.115 + */
1.116 + public ClientParamsStack(ClientParamsStack stack) {
1.117 + this(stack.getApplicationParams(),
1.118 + stack.getClientParams(),
1.119 + stack.getRequestParams(),
1.120 + stack.getOverrideParams());
1.121 + }
1.122 +
1.123 +
1.124 + /**
1.125 + * Creates a modified copy of a parameter stack.
1.126 + * The new stack will contain the explicitly passed elements.
1.127 + * For elements where the explicit argument is <code>null</code>,
1.128 + * the corresponding element from the argument stack is used.
1.129 + * There is no copying of parameters.
1.130 + *
1.131 + * @param stack the stack to modify
1.132 + * @param aparams application parameters, or <code>null</code>
1.133 + * @param cparams client parameters, or <code>null</code>
1.134 + * @param rparams request parameters, or <code>null</code>
1.135 + * @param oparams override parameters, or <code>null</code>
1.136 + */
1.137 + public ClientParamsStack(ClientParamsStack stack,
1.138 + HttpParams aparams, HttpParams cparams,
1.139 + HttpParams rparams, HttpParams oparams) {
1.140 + this((aparams != null) ? aparams : stack.getApplicationParams(),
1.141 + (cparams != null) ? cparams : stack.getClientParams(),
1.142 + (rparams != null) ? rparams : stack.getRequestParams(),
1.143 + (oparams != null) ? oparams : stack.getOverrideParams());
1.144 + }
1.145 +
1.146 +
1.147 + /**
1.148 + * Obtains the application parameters of this stack.
1.149 + *
1.150 + * @return the application parameters, or <code>null</code>
1.151 + */
1.152 + public final HttpParams getApplicationParams() {
1.153 + return applicationParams;
1.154 + }
1.155 +
1.156 + /**
1.157 + * Obtains the client parameters of this stack.
1.158 + *
1.159 + * @return the client parameters, or <code>null</code>
1.160 + */
1.161 + public final HttpParams getClientParams() {
1.162 + return clientParams;
1.163 + }
1.164 +
1.165 + /**
1.166 + * Obtains the request parameters of this stack.
1.167 + *
1.168 + * @return the request parameters, or <code>null</code>
1.169 + */
1.170 + public final HttpParams getRequestParams() {
1.171 + return requestParams;
1.172 + }
1.173 +
1.174 + /**
1.175 + * Obtains the override parameters of this stack.
1.176 + *
1.177 + * @return the override parameters, or <code>null</code>
1.178 + */
1.179 + public final HttpParams getOverrideParams() {
1.180 + return overrideParams;
1.181 + }
1.182 +
1.183 +
1.184 + /**
1.185 + * Obtains a parameter from this stack.
1.186 + * See class comment for search order.
1.187 + *
1.188 + * @param name the name of the parameter to obtain
1.189 + *
1.190 + * @return the highest-priority value for that parameter, or
1.191 + * <code>null</code> if it is not set anywhere in this stack
1.192 + */
1.193 + public Object getParameter(String name) {
1.194 + if (name == null) {
1.195 + throw new IllegalArgumentException
1.196 + ("Parameter name must not be null.");
1.197 + }
1.198 +
1.199 + Object result = null;
1.200 +
1.201 + if (overrideParams != null) {
1.202 + result = overrideParams.getParameter(name);
1.203 + }
1.204 + if ((result == null) && (requestParams != null)) {
1.205 + result = requestParams.getParameter(name);
1.206 + }
1.207 + if ((result == null) && (clientParams != null)) {
1.208 + result = clientParams.getParameter(name);
1.209 + }
1.210 + if ((result == null) && (applicationParams != null)) {
1.211 + result = applicationParams.getParameter(name);
1.212 + }
1.213 + return result;
1.214 + }
1.215 +
1.216 + /**
1.217 + * Does <i>not</i> set a parameter.
1.218 + * Parameter stacks are read-only. It is possible, though discouraged,
1.219 + * to access and modify specific stack entries.
1.220 + * Derived classes may change this behavior.
1.221 + *
1.222 + * @param name ignored
1.223 + * @param value ignored
1.224 + *
1.225 + * @return nothing
1.226 + *
1.227 + * @throws UnsupportedOperationException always
1.228 + */
1.229 + public HttpParams setParameter(String name, Object value)
1.230 + throws UnsupportedOperationException {
1.231 +
1.232 + throw new UnsupportedOperationException
1.233 + ("Setting parameters in a stack is not supported.");
1.234 + }
1.235 +
1.236 +
1.237 + /**
1.238 + * Does <i>not</i> remove a parameter.
1.239 + * Parameter stacks are read-only. It is possible, though discouraged,
1.240 + * to access and modify specific stack entries.
1.241 + * Derived classes may change this behavior.
1.242 + *
1.243 + * @param name ignored
1.244 + *
1.245 + * @return nothing
1.246 + *
1.247 + * @throws UnsupportedOperationException always
1.248 + */
1.249 + public boolean removeParameter(String name) {
1.250 + throw new UnsupportedOperationException
1.251 + ("Removing parameters in a stack is not supported.");
1.252 + }
1.253 +
1.254 +
1.255 + /**
1.256 + * Does <i>not</i> copy parameters.
1.257 + * Parameter stacks are lightweight objects, expected to be instantiated
1.258 + * as needed and to be used only in a very specific context. On top of
1.259 + * that, they are read-only. The typical copy operation to prevent
1.260 + * accidental modification of parameters passed by the application to
1.261 + * a framework object is therefore pointless and disabled.
1.262 + * Create a new stack if you really need a copy.
1.263 + * <br/>
1.264 + * Derived classes may change this behavior.
1.265 + *
1.266 + * @return <code>this</code> parameter stack
1.267 + */
1.268 + public HttpParams copy() {
1.269 + return this;
1.270 + }
1.271 +
1.272 +
1.273 +}
