View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/params/HttpClientParams.java $
3    * $Revision$
4    * $Date$
5    *
6    * ====================================================================
7    *
8    *  Licensed to the Apache Software Foundation (ASF) under one or more
9    *  contributor license agreements.  See the NOTICE file distributed with
10   *  this work for additional information regarding copyright ownership.
11   *  The ASF licenses this file to You under the Apache License, Version 2.0
12   *  (the "License"); you may not use this file except in compliance with
13   *  the License.  You may obtain a copy of the License at
14   *
15   *      http://www.apache.org/licenses/LICENSE-2.0
16   *
17   *  Unless required by applicable law or agreed to in writing, software
18   *  distributed under the License is distributed on an "AS IS" BASIS,
19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   *  See the License for the specific language governing permissions and
21   *  limitations under the License.
22   * ====================================================================
23   *
24   * This software consists of voluntary contributions made by many
25   * individuals on behalf of the Apache Software Foundation.  For more
26   * information on the Apache Software Foundation, please see
27   * <http://www.apache.org/>.
28   *
29   */
30  
31  package org.apache.commons.httpclient.params;
32  
33  /***
34   * This class represents a collection of HTTP protocol parameters applicable to 
35   * {@link org.apache.commons.httpclient.HttpClient instances of HttpClient}. 
36   * Protocol parameters may be linked together to form a hierarchy. If a particular 
37   * parameter value has not been explicitly defined in the collection itself, its 
38   * value will be drawn from the parent collection of parameters.
39   * 
40   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
41   * 
42   * @version $Revision$
43   * 
44   * @since 3.0
45   */
46  public class HttpClientParams extends HttpMethodParams {
47  
48      /***
49       * Sets the timeout in milliseconds used when retrieving an 
50       * {@link org.apache.commons.httpclient.HttpConnection HTTP connection} from the
51       * {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}.
52       * <p>
53       * This parameter expects a value of type {@link Long}.
54       * </p>
55       */ 
56      public static final String CONNECTION_MANAGER_TIMEOUT = "http.connection-manager.timeout"; 
57  
58      /***
59       * Defines the default 
60       * {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}
61       * class.
62       * <p>
63       * This parameter expects a value of type {@link Class}.
64       * </p>
65       */ 
66      public static final String CONNECTION_MANAGER_CLASS = "http.connection-manager.class"; 
67  
68      /***
69       * Defines whether authentication should be attempted preemptively.
70       * <p>
71       * This parameter expects a value of type {@link Boolean}.
72       * </p>
73       */
74      public static final String PREEMPTIVE_AUTHENTICATION = "http.authentication.preemptive";
75  
76      /***
77       * Defines whether relative redirects should be rejected.
78       * <p>
79       * This parameter expects a value of type {@link Boolean}.
80       * </p>
81       */
82      public static final String REJECT_RELATIVE_REDIRECT = "http.protocol.reject-relative-redirect"; 
83  
84      /*** 
85       * Defines the maximum number of redirects to be followed. 
86       * The limit on number of redirects is intended to prevent infinite loops. 
87       * <p>
88       * This parameter expects a value of type {@link Integer}.
89       * </p>
90       */
91      public static final String MAX_REDIRECTS = "http.protocol.max-redirects";
92  
93      /*** 
94       * Defines whether circular redirects (redirects to the same location) should be allowed. 
95       * The HTTP spec is not sufficiently clear whether circular redirects are permitted, 
96       * therefore optionally they can be enabled
97       * <p>
98       * This parameter expects a value of type {@link Boolean}.
99       * </p>
100      */
101     public static final String ALLOW_CIRCULAR_REDIRECTS = "http.protocol.allow-circular-redirects";
102 
103     /***
104      * Creates a new collection of parameters with the collection returned
105      * by {@link #getDefaultParams()} as a parent. The collection will defer
106      * to its parent for a default value if a particular parameter is not 
107      * explicitly set in the collection itself.
108      * 
109      * @see #getDefaultParams()
110      */
111     public HttpClientParams() {
112         super();
113     }
114 
115     /***
116      * Creates a new collection of parameters with the given parent. 
117      * The collection will defer to its parent for a default value 
118      * if a particular parameter is not explicitly set in the collection
119      * itself.
120      * 
121      * @param defaults the parent collection to defer to, if a parameter
122      * is not explictly set in the collection itself.
123      *
124      * @see #getDefaultParams()
125      */
126     public HttpClientParams(HttpParams defaults) {
127         super(defaults);
128     }
129 
130     /***
131      * Returns the timeout in milliseconds used when retrieving an 
132      * {@link org.apache.commons.httpclient.HttpConnection HTTP connection} from the
133      * {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}.
134      * 
135      * @return timeout in milliseconds.
136      */ 
137     public long getConnectionManagerTimeout() {
138         return getLongParameter(CONNECTION_MANAGER_TIMEOUT, 0);
139     }
140 
141     /***
142      * Sets the timeout in milliseconds used when retrieving an 
143      * {@link org.apache.commons.httpclient.HttpConnection HTTP connection} from the
144      * {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}.
145      * 
146      * @param timeout the timeout in milliseconds
147      */ 
148     public void setConnectionManagerTimeout(long timeout) {
149         setLongParameter(CONNECTION_MANAGER_TIMEOUT, timeout);
150     }
151 
152     /***
153      * Returns the default 
154      * {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}
155      * class.
156      * @return {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}
157      * factory class.
158      */ 
159     public Class getConnectionManagerClass() {
160         return (Class) getParameter(CONNECTION_MANAGER_CLASS);
161     }
162 
163     /***
164      * Sets {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}
165      * class to be used der default.
166      * @param clazz 
167      *  {@link org.apache.commons.httpclient.HttpConnectionManager HTTP connection manager}
168      *  factory class.
169      */ 
170     public void setConnectionManagerClass(Class clazz) {
171         setParameter(CONNECTION_MANAGER_CLASS, clazz);
172     }
173     
174     /***
175      * Returns <tt>true</tt> if authentication should be attempted preemptively, 
176      * <tt>false</tt> otherwise.
177      * 
178      * @return <tt>true</tt> if authentication should be attempted preemptively,
179      *   <tt>false</tt> otherwise.
180      */
181     public boolean isAuthenticationPreemptive() {
182         return getBooleanParameter(PREEMPTIVE_AUTHENTICATION, false); 
183     }
184 
185     /***
186      * Sets whether authentication should be attempted preemptively.
187      * 
188      * @param value <tt>true</tt> if authentication should be attempted preemptively,
189      *   <tt>false</tt> otherwise.
190      */
191     public void setAuthenticationPreemptive(boolean value) {
192         setBooleanParameter(PREEMPTIVE_AUTHENTICATION, value); 
193     }
194 
195     private static final String[] PROTOCOL_STRICTNESS_PARAMETERS = {
196         REJECT_RELATIVE_REDIRECT,
197         ALLOW_CIRCULAR_REDIRECTS
198     };
199 
200 
201     public void makeStrict() {
202         super.makeStrict();
203         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.TRUE);
204     }
205 
206 
207     public void makeLenient() {
208         super.makeLenient();
209         setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.FALSE);
210     }
211 }