1 /* 2 * ==================================================================== 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * ==================================================================== 20 * 21 * This software consists of voluntary contributions made by many 22 * individuals on behalf of the Apache Software Foundation. For more 23 * information on the Apache Software Foundation, please see 24 * <http://www.apache.org/>. 25 * 26 */ 27 28 package org.apache.http.impl.client; 29 30 import org.apache.http.params.AbstractHttpParams; 31 import org.apache.http.params.HttpParams; 32 import org.apache.http.util.Args; 33 34 /** 35 * Represents a stack of parameter collections. 36 * When retrieving a parameter, the stack is searched in a fixed order 37 * and the first match returned. Setting parameters via the stack is 38 * not supported. To minimize overhead, the stack has a fixed size and 39 * does not maintain an internal array. 40 * The supported stack entries, sorted by increasing priority, are: 41 * <ol> 42 * <li>Application parameters: 43 * expected to be the same for all clients used by an application. 44 * These provide "global", that is application-wide, defaults. 45 * </li> 46 * <li>Client parameters: 47 * specific to an instance of 48 * {@link org.apache.http.client.HttpClient HttpClient}. 49 * These provide client specific defaults. 50 * </li> 51 * <li>Request parameters: 52 * specific to a single request execution. 53 * For overriding client and global defaults. 54 * </li> 55 * <li>Override parameters: 56 * specific to an instance of 57 * {@link org.apache.http.client.HttpClient HttpClient}. 58 * These can be used to set parameters that cannot be overridden 59 * on a per-request basis. 60 * </li> 61 * </ol> 62 * Each stack entry may be {@code null}. That is preferable over 63 * an empty params collection, since it avoids searching the empty collection 64 * when looking up parameters. 65 * 66 * @since 4.0 67 * 68 * @deprecated (4.3) use configuration classes provided 'org.apache.http.config' 69 * and 'org.apache.http.client.config' 70 */ 71 @Deprecated 72 public class ClientParamsStack extends AbstractHttpParams { 73 74 /** The application parameter collection, or {@code null}. */ 75 protected final HttpParams applicationParams; 76 77 /** The client parameter collection, or {@code null}. */ 78 protected final HttpParams clientParams; 79 80 /** The request parameter collection, or {@code null}. */ 81 protected final HttpParams requestParams; 82 83 /** The override parameter collection, or {@code null}. */ 84 protected final HttpParams overrideParams; 85 86 87 /** 88 * Creates a new parameter stack from elements. 89 * The arguments will be stored as-is, there is no copying to 90 * prevent modification. 91 * 92 * @param aparams application parameters, or {@code null} 93 * @param cparams client parameters, or {@code null} 94 * @param rparams request parameters, or {@code null} 95 * @param oparams override parameters, or {@code null} 96 */ 97 public ClientParamsStack(final HttpParams aparams, final HttpParams cparams, 98 final HttpParams rparams, final HttpParams oparams) { 99 applicationParams = aparams; 100 clientParams = cparams; 101 requestParams = rparams; 102 overrideParams = oparams; 103 } 104 105 106 /** 107 * Creates a copy of a parameter stack. 108 * The new stack will have the exact same entries as the argument stack. 109 * There is no copying of parameters. 110 * 111 * @param stack the stack to copy 112 */ 113 public ClientParamsStacklientParamsStack.html#ClientParamsStack">ClientParamsStack(final ClientParamsStack stack) { 114 this(stack.getApplicationParams(), 115 stack.getClientParams(), 116 stack.getRequestParams(), 117 stack.getOverrideParams()); 118 } 119 120 121 /** 122 * Creates a modified copy of a parameter stack. 123 * The new stack will contain the explicitly passed elements. 124 * For elements where the explicit argument is {@code null}, 125 * the corresponding element from the argument stack is used. 126 * There is no copying of parameters. 127 * 128 * @param stack the stack to modify 129 * @param aparams application parameters, or {@code null} 130 * @param cparams client parameters, or {@code null} 131 * @param rparams request parameters, or {@code null} 132 * @param oparams override parameters, or {@code null} 133 */ 134 public ClientParamsStacklientParamsStack.html#ClientParamsStack">ClientParamsStack(final ClientParamsStack stack, 135 final HttpParams aparams, final HttpParams cparams, 136 final HttpParams rparams, final HttpParams oparams) { 137 this((aparams != null) ? aparams : stack.getApplicationParams(), 138 (cparams != null) ? cparams : stack.getClientParams(), 139 (rparams != null) ? rparams : stack.getRequestParams(), 140 (oparams != null) ? oparams : stack.getOverrideParams()); 141 } 142 143 144 /** 145 * Obtains the application parameters of this stack. 146 * 147 * @return the application parameters, or {@code null} 148 */ 149 public final HttpParams getApplicationParams() { 150 return applicationParams; 151 } 152 153 /** 154 * Obtains the client parameters of this stack. 155 * 156 * @return the client parameters, or {@code null} 157 */ 158 public final HttpParams getClientParams() { 159 return clientParams; 160 } 161 162 /** 163 * Obtains the request parameters of this stack. 164 * 165 * @return the request parameters, or {@code null} 166 */ 167 public final HttpParams getRequestParams() { 168 return requestParams; 169 } 170 171 /** 172 * Obtains the override parameters of this stack. 173 * 174 * @return the override parameters, or {@code null} 175 */ 176 public final HttpParams getOverrideParams() { 177 return overrideParams; 178 } 179 180 181 /** 182 * Obtains a parameter from this stack. 183 * See class comment for search order. 184 * 185 * @param name the name of the parameter to obtain 186 * 187 * @return the highest-priority value for that parameter, or 188 * {@code null} if it is not set anywhere in this stack 189 */ 190 @Override 191 public Object getParameter(final String name) { 192 Args.notNull(name, "Parameter name"); 193 194 Object result = null; 195 196 if (overrideParams != null) { 197 result = overrideParams.getParameter(name); 198 } 199 if ((result == null) && (requestParams != null)) { 200 result = requestParams.getParameter(name); 201 } 202 if ((result == null) && (clientParams != null)) { 203 result = clientParams.getParameter(name); 204 } 205 if ((result == null) && (applicationParams != null)) { 206 result = applicationParams.getParameter(name); 207 } 208 return result; 209 } 210 211 /** 212 * Does <i>not</i> set a parameter. 213 * Parameter stacks are read-only. It is possible, though discouraged, 214 * to access and modify specific stack entries. 215 * Derived classes may change this behavior. 216 * 217 * @param name ignored 218 * @param value ignored 219 * 220 * @return nothing 221 * 222 * @throws UnsupportedOperationException always 223 */ 224 @Override 225 public HttpParams setParameter(final String name, final Object value) 226 throws UnsupportedOperationException { 227 228 throw new UnsupportedOperationException 229 ("Setting parameters in a stack is not supported."); 230 } 231 232 233 /** 234 * Does <i>not</i> remove a parameter. 235 * Parameter stacks are read-only. It is possible, though discouraged, 236 * to access and modify specific stack entries. 237 * Derived classes may change this behavior. 238 * 239 * @param name ignored 240 * 241 * @return nothing 242 * 243 * @throws UnsupportedOperationException always 244 */ 245 @Override 246 public boolean removeParameter(final String name) { 247 throw new UnsupportedOperationException 248 ("Removing parameters in a stack is not supported."); 249 } 250 251 252 /** 253 * Does <i>not</i> copy parameters. 254 * Parameter stacks are lightweight objects, expected to be instantiated 255 * as needed and to be used only in a very specific context. On top of 256 * that, they are read-only. The typical copy operation to prevent 257 * accidental modification of parameters passed by the application to 258 * a framework object is therefore pointless and disabled. 259 * Create a new stack if you really need a copy. 260 * <p> 261 * Derived classes may change this behavior. 262 * </p> 263 * 264 * @return {@code this} parameter stack 265 */ 266 @Override 267 public HttpParams copy() { 268 return this; 269 } 270 271 272 }