001: /*
002: * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/params/HttpMethodParams.java,v 1.17 2004/10/06 17:32:04 olegk Exp $
003: * $Revision: 483949 $
004: * $Date: 2006-12-08 12:34:50 +0100 (Fri, 08 Dec 2006) $
005: *
006: * ====================================================================
007: *
008: * Licensed to the Apache Software Foundation (ASF) under one or more
009: * contributor license agreements. See the NOTICE file distributed with
010: * this work for additional information regarding copyright ownership.
011: * The ASF licenses this file to You under the Apache License, Version 2.0
012: * (the "License"); you may not use this file except in compliance with
013: * the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing, software
018: * distributed under the License is distributed on an "AS IS" BASIS,
019: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020: * See the License for the specific language governing permissions and
021: * limitations under the License.
022: * ====================================================================
023: *
024: * This software consists of voluntary contributions made by many
025: * individuals on behalf of the Apache Software Foundation. For more
026: * information on the Apache Software Foundation, please see
027: * <http://www.apache.org/>.
028: *
029: */
030:
031: package org.apache.commons.httpclient.params;
032:
033: import org.apache.commons.httpclient.HttpVersion;
034: import org.apache.commons.httpclient.cookie.CookiePolicy;
035: import org.apache.commons.logging.Log;
036: import org.apache.commons.logging.LogFactory;
037:
038: /**
039: * This class represents a collection of HTTP protocol parameters applicable to
040: * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}. Protocol
041: * parameters may be linked together to form a hierarchy. If a particular
042: * parameter value has not been explicitly defined in the collection itself,
043: * its value will be drawn from the parent collection of parameters.
044: *
045: * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
046: * @author Christian Kohlschuetter
047: *
048: * @version $Revision: 483949 $
049: *
050: * @since 3.0
051: */
052: public class HttpMethodParams extends DefaultHttpParams {
053:
054: /** Log object for this class. */
055: private static final Log LOG = LogFactory
056: .getLog(HttpMethodParams.class);
057:
058: /**
059: * Defines the content of the <tt>User-Agent</tt> header used by
060: * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}.
061: * <p>
062: * This parameter expects a value of type {@link String}.
063: * </p>
064: */
065: public static final String USER_AGENT = "http.useragent";
066:
067: /**
068: * Defines the {@link HttpVersion HTTP protocol version} used by
069: * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} per
070: * default.
071: * <p>
072: * This parameter expects a value of type {@link HttpVersion}.
073: * </p>
074: */
075: public static final String PROTOCOL_VERSION = "http.protocol.version";
076:
077: /**
078: * Defines whether {@link org.apache.commons.httpclient.HttpMethod HTTP methods} should
079: * reject ambiguous {@link org.apache.commons.httpclient.StatusLine HTTP status line}.
080: * <p>
081: * This parameter expects a value of type {@link Boolean}.
082: * </p>
083: */
084: public static final String UNAMBIGUOUS_STATUS_LINE = "http.protocol.unambiguous-statusline";
085:
086: /**
087: * Defines whether {@link org.apache.commons.httpclient.Cookie cookies} should be put on
088: * a single {@link org.apache.commons.httpclient.Header response header}.
089: * <p>
090: * This parameter expects a value of type {@link Boolean}.
091: * </p>
092: */
093: public static final String SINGLE_COOKIE_HEADER = "http.protocol.single-cookie-header";
094:
095: /**
096: * Defines whether responses with an invalid <tt>Transfer-Encoding</tt> header should be
097: * rejected.
098: * <p>
099: * This parameter expects a value of type {@link Boolean}.
100: * </p>
101: */
102: public static final String STRICT_TRANSFER_ENCODING = "http.protocol.strict-transfer-encoding";
103:
104: /**
105: * Defines whether the content body sent in response to
106: * {@link org.apache.commons.httpclient.methods.HeadMethod} should be rejected.
107: * <p>
108: * This parameter expects a value of type {@link Boolean}.
109: * </p>
110: */
111: public static final String REJECT_HEAD_BODY = "http.protocol.reject-head-body";
112:
113: /**
114: * Sets period of time in milliseconds to wait for a content body sent in response to
115: * {@link org.apache.commons.httpclient.methods.HeadMethod HEAD method} from a
116: * non-compliant server. If the parameter is not set or set to <tt>-1</tt> non-compliant
117: * response body check is disabled.
118: * <p>
119: * This parameter expects a value of type {@link Integer}.
120: * </p>
121: */
122: public static final String HEAD_BODY_CHECK_TIMEOUT = "http.protocol.head-body-timeout";
123:
124: /**
125: * <p>
126: * Activates 'Expect: 100-Continue' handshake for the
127: * {@link org.apache.commons.httpclient.methods.ExpectContinueMethod
128: * entity enclosing methods}. The purpose of the 'Expect: 100-Continue'
129: * handshake to allow a client that is sending a request message with
130: * a request body to determine if the origin server is willing to
131: * accept the request (based on the request headers) before the client
132: * sends the request body.
133: * </p>
134: *
135: * <p>
136: * The use of the 'Expect: 100-continue' handshake can result in
137: * noticable peformance improvement for entity enclosing requests
138: * (such as POST and PUT) that require the target server's
139: * authentication.
140: * </p>
141: *
142: * <p>
143: * 'Expect: 100-continue' handshake should be used with
144: * caution, as it may cause problems with HTTP servers and
145: * proxies that do not support HTTP/1.1 protocol.
146: * </p>
147: *
148: * This parameter expects a value of type {@link Boolean}.
149: */
150: public static final String USE_EXPECT_CONTINUE = "http.protocol.expect-continue";
151:
152: /**
153: * Defines the charset to be used when encoding
154: * {@link org.apache.commons.httpclient.Credentials}. If not defined then the
155: * {@link #HTTP_ELEMENT_CHARSET} should be used.
156: * <p>
157: * This parameter expects a value of type {@link String}.
158: * </p>
159: */
160: public static final String CREDENTIAL_CHARSET = "http.protocol.credential-charset";
161:
162: /**
163: * Defines the charset to be used for encoding HTTP protocol elements.
164: * <p>
165: * This parameter expects a value of type {@link String}.
166: * </p>
167: */
168: public static final String HTTP_ELEMENT_CHARSET = "http.protocol.element-charset";
169:
170: /**
171: * Defines the charset to be used for parsing URIs.
172: * <p>
173: * This parameter expects a value of type {@link String}.
174: * </p>
175: */
176: public static final String HTTP_URI_CHARSET = "http.protocol.uri-charset";
177:
178: /**
179: * Defines the charset to be used for encoding content body.
180: * <p>
181: * This parameter expects a value of type {@link String}.
182: * </p>
183: */
184: public static final String HTTP_CONTENT_CHARSET = "http.protocol.content-charset";
185:
186: /**
187: * Defines {@link CookiePolicy cookie policy} to be used for cookie management.
188: * <p>
189: * This parameter expects a value of type {@link String}.
190: * </p>
191: */
192: public static final String COOKIE_POLICY = "http.protocol.cookie-policy";
193:
194: /**
195: * Defines HttpClient's behavior when a response provides more bytes than
196: * expected (specified with Content-Length, for example).
197: * <p>
198: * Such surplus data makes the HTTP connection unreliable for keep-alive
199: * requests, as malicious response data (faked headers etc.) can lead to undesired
200: * results on the next request using that connection.
201: * </p>
202: * <p>
203: * If this parameter is set to <code>true</code>, any detection of extra
204: * input data will generate a warning in the log.
205: * </p>
206: * <p>
207: * This parameter expects a value of type {@link Boolean}.
208: * </p>
209: */
210: public static final String WARN_EXTRA_INPUT = "http.protocol.warn-extra-input";
211:
212: /**
213: * Defines the maximum number of ignorable lines before we expect
214: * a HTTP response's status code.
215: * <p>
216: * With HTTP/1.1 persistent connections, the problem arises that
217: * broken scripts could return a wrong Content-Length
218: * (there are more bytes sent than specified).<br />
219: * Unfortunately, in some cases, this is not possible after the bad response,
220: * but only before the next one. <br />
221: * So, HttpClient must be able to skip those surplus lines this way.
222: * </p>
223: * <p>
224: * Set this to 0 to disallow any garbage/empty lines before the status line.<br />
225: * To specify no limit, use {@link java.lang.Integer#MAX_VALUE} (default in lenient mode).
226: * </p>
227: *
228: * This parameter expects a value of type {@link Integer}.
229: */
230: public static final String STATUS_LINE_GARBAGE_LIMIT = "http.protocol.status-line-garbage-limit";
231:
232: /**
233: * Sets the socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds to be used when executing the method.
234: * A timeout value of zero is interpreted as an infinite timeout.
235: * <p>
236: * This parameter expects a value of type {@link Integer}.
237: * </p>
238: * @see java.net.SocketOptions#SO_TIMEOUT
239: */
240: public static final String SO_TIMEOUT = "http.socket.timeout";
241:
242: /**
243: * The key used to look up the date patterns used for parsing. The String patterns are stored
244: * in a {@link java.util.Collection} and must be compatible with
245: * {@link java.text.SimpleDateFormat}.
246: * <p>
247: * This parameter expects a value of type {@link java.util.Collection}.
248: * </p>
249: */
250: public static final String DATE_PATTERNS = "http.dateparser.patterns";
251:
252: /**
253: * Sets the method retry handler parameter.
254: * <p>
255: * This parameter expects a value of type {@link org.apache.commons.httpclient.HttpMethodRetryHandler}.
256: * </p>
257: */
258: public static final String RETRY_HANDLER = "http.method.retry-handler";
259:
260: /**
261: * Sets the maximum buffered response size (in bytes) that triggers no warning. Buffered
262: * responses exceeding this size will trigger a warning in the log.
263: * <p>
264: * This parameter expects a value if type {@link Integer}.
265: * </p>
266: */
267: public static final String BUFFER_WARN_TRIGGER_LIMIT = "http.method.response.buffer.warnlimit";
268:
269: /**
270: * Defines the virtual host name.
271: * <p>
272: * This parameter expects a value of type {@link java.lang.String}.
273: * </p>
274: */
275: public static final String VIRTUAL_HOST = "http.virtual-host";
276:
277: /**
278: * Sets the value to use as the multipart boundary.
279: * <p>
280: * This parameter expects a value if type {@link String}.
281: * </p>
282: * @see org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity
283: */
284: public static final String MULTIPART_BOUNDARY = "http.method.multipart.boundary";
285:
286: /**
287: * Creates a new collection of parameters with the collection returned
288: * by {@link #getDefaultParams()} as a parent. The collection will defer
289: * to its parent for a default value if a particular parameter is not
290: * explicitly set in the collection itself.
291: *
292: * @see #getDefaultParams()
293: */
294: public HttpMethodParams() {
295: super (getDefaultParams());
296: }
297:
298: /**
299: * Creates a new collection of parameters with the given parent.
300: * The collection will defer to its parent for a default value
301: * if a particular parameter is not explicitly set in the collection
302: * itself.
303: *
304: * @param defaults the parent collection to defer to, if a parameter
305: * is not explictly set in the collection itself.
306: *
307: * @see #getDefaultParams()
308: */
309: public HttpMethodParams(HttpParams defaults) {
310: super (defaults);
311: }
312:
313: /**
314: * Returns the charset to be used for writing HTTP headers.
315: * @return The charset
316: */
317: public String getHttpElementCharset() {
318: String charset = (String) getParameter(HTTP_ELEMENT_CHARSET);
319: if (charset == null) {
320: LOG
321: .warn("HTTP element charset not configured, using US-ASCII");
322: charset = "US-ASCII";
323: }
324: return charset;
325: }
326:
327: /**
328: * Sets the charset to be used for writing HTTP headers.
329: * @param charset The charset
330: */
331: public void setHttpElementCharset(String charset) {
332: setParameter(HTTP_ELEMENT_CHARSET, charset);
333: }
334:
335: /**
336: * Returns the default charset to be used for writing content body,
337: * when no charset explicitly specified.
338: * @return The charset
339: */
340: public String getContentCharset() {
341: String charset = (String) getParameter(HTTP_CONTENT_CHARSET);
342: if (charset == null) {
343: LOG
344: .warn("Default content charset not configured, using ISO-8859-1");
345: charset = "ISO-8859-1";
346: }
347: return charset;
348: }
349:
350: /**
351: * Sets the charset to be used for parsing URIs.
352: * @param charset The charset
353: */
354: public void setUriCharset(String charset) {
355: setParameter(HTTP_URI_CHARSET, charset);
356: }
357:
358: /**
359: * Returns the charset to be used for parsing URIs.
360: * @return The charset
361: */
362: public String getUriCharset() {
363: String charset = (String) getParameter(HTTP_URI_CHARSET);
364: if (charset == null) {
365: charset = "UTF-8";
366: }
367: return charset;
368: }
369:
370: /**
371: * Sets the default charset to be used for writing content body,
372: * when no charset explicitly specified.
373: * @param charset The charset
374: */
375: public void setContentCharset(String charset) {
376: setParameter(HTTP_CONTENT_CHARSET, charset);
377: }
378:
379: /**
380: * Returns the charset to be used for {@link org.apache.commons.httpclient.Credentials}. If
381: * not configured the {@link #HTTP_ELEMENT_CHARSET HTTP element charset} is used.
382: * @return The charset
383: */
384: public String getCredentialCharset() {
385: String charset = (String) getParameter(CREDENTIAL_CHARSET);
386: if (charset == null) {
387: LOG
388: .debug("Credential charset not configured, using HTTP element charset");
389: charset = getHttpElementCharset();
390: }
391: return charset;
392: }
393:
394: /**
395: * Sets the charset to be used for writing HTTP headers.
396: * @param charset The charset
397: */
398: public void setCredentialCharset(String charset) {
399: setParameter(CREDENTIAL_CHARSET, charset);
400: }
401:
402: /**
403: * Returns {@link HttpVersion HTTP protocol version} to be used by the
404: * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that
405: * this collection of parameters applies to.
406: *
407: * @return {@link HttpVersion HTTP protocol version}
408: */
409: public HttpVersion getVersion() {
410: Object param = getParameter(PROTOCOL_VERSION);
411: if (param == null) {
412: return HttpVersion.HTTP_1_1;
413: }
414: return (HttpVersion) param;
415: }
416:
417: /**
418: * Assigns the {@link HttpVersion HTTP protocol version} to be used by the
419: * {@link org.apache.commons.httpclient.HttpMethod HTTP methods} that
420: * this collection of parameters applies to.
421: *
422: * @param version the {@link HttpVersion HTTP protocol version}
423: */
424: public void setVersion(HttpVersion version) {
425: setParameter(PROTOCOL_VERSION, version);
426: }
427:
428: /**
429: * Returns {@link CookiePolicy cookie policy} to be used by the
430: * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
431: * this collection of parameters applies to.
432: *
433: * @return {@link CookiePolicy cookie policy}
434: */
435: public String getCookiePolicy() {
436: Object param = getParameter(COOKIE_POLICY);
437: if (param == null) {
438: return CookiePolicy.DEFAULT;
439: }
440: return (String) param;
441: }
442:
443: /**
444: * Assigns the {@link CookiePolicy cookie policy} to be used by the
445: * {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
446: * this collection of parameters applies to.
447: *
448: * @param policy the {@link CookiePolicy cookie policy}
449: */
450: public void setCookiePolicy(String policy) {
451: setParameter(COOKIE_POLICY, policy);
452: }
453:
454: /**
455: * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
456: * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
457: * timeout.
458: *
459: * @return timeout in milliseconds
460: */
461: public int getSoTimeout() {
462: return getIntParameter(SO_TIMEOUT, 0);
463: }
464:
465: /**
466: * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
467: * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
468: * timeout.
469: *
470: * @param timeout Timeout in milliseconds
471: */
472: public void setSoTimeout(int timeout) {
473: setIntParameter(SO_TIMEOUT, timeout);
474: }
475:
476: /**
477: * Sets the virtual host name.
478: *
479: * @param hostname The host name
480: */
481: public void setVirtualHost(final String hostname) {
482: setParameter(VIRTUAL_HOST, hostname);
483: }
484:
485: /**
486: * Returns the virtual host name.
487: *
488: * @return The virtual host name
489: */
490: public String getVirtualHost() {
491: return (String) getParameter(VIRTUAL_HOST);
492: }
493:
494: private static final String[] PROTOCOL_STRICTNESS_PARAMETERS = {
495: UNAMBIGUOUS_STATUS_LINE, SINGLE_COOKIE_HEADER,
496: STRICT_TRANSFER_ENCODING, REJECT_HEAD_BODY,
497: WARN_EXTRA_INPUT };
498:
499: /**
500: * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
501: * strictly follow the HTTP protocol specification (RFC 2616 and other relevant RFCs).
502: * It must be noted that popular HTTP agents have different degree of HTTP protocol
503: * compliance and some HTTP serves are programmed to expect the behaviour that does not
504: * strictly adhere to the HTTP specification.
505: */
506: public void makeStrict() {
507: setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.TRUE);
508: setIntParameter(STATUS_LINE_GARBAGE_LIMIT, 0);
509: }
510:
511: /**
512: * Makes the {@link org.apache.commons.httpclient.HttpMethod HTTP methods}
513: * attempt to mimic the exact behaviour of commonly used HTTP agents,
514: * which many HTTP servers expect, even though such behaviour may violate
515: * the HTTP protocol specification (RFC 2616 and other relevant RFCs).
516: */
517: public void makeLenient() {
518: setParameters(PROTOCOL_STRICTNESS_PARAMETERS, Boolean.FALSE);
519: setIntParameter(STATUS_LINE_GARBAGE_LIMIT, Integer.MAX_VALUE);
520: }
521:
522: }
|