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: 480424 $
    4    * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
    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: 480424 $
    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 }