View Javadoc

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