View Javadoc

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.params;
29  
30  /**
31   * HttpParams interface represents a collection of immutable values that define
32   * a runtime behavior of a component. HTTP parameters should be simple objects:
33   * integers, doubles, strings, collections and objects that remain immutable
34   * at runtime. HttpParams is expected to be used in 'write once - read many' mode.
35   * Once initialized, HTTP parameters are not expected to mutate in
36   * the course of HTTP message processing.
37   * <p>
38   * The purpose of this interface is to define a behavior of other components.
39   * Usually each complex component has its own HTTP parameter collection.
40   * <p>
41   * Instances of this interface can be linked together to form a hierarchy.
42   * In the simplest form one set of parameters can use content of another one
43   * to obtain default values of parameters not present in the local set.
44   *
45   * @see DefaultedHttpParams
46   *
47   * @since 4.0
48   */
49  public interface HttpParams {
50  
51      /**
52       * Obtains the value of the given parameter.
53       *
54       * @param name the parent name.
55       *
56       * @return  an object that represents the value of the parameter,
57       *          <code>null</code> if the parameter is not set or if it
58       *          is explicitly set to <code>null</code>
59       *
60       * @see #setParameter(String, Object)
61       */
62      Object getParameter(String name);
63  
64      /**
65       * Assigns the value to the parameter with the given name.
66       *
67       * @param name parameter name
68       * @param value parameter value
69       */
70      HttpParams setParameter(String name, Object value);
71  
72      /**
73       * Creates a copy of these parameters.
74       *
75       * @return  a new set of parameters holding the same values as this one
76       *
77       * @deprecated (4.1)
78       */
79      @Deprecated
80      HttpParams copy();
81  
82      /**
83       * Removes the parameter with the specified name.
84       *
85       * @param name parameter name
86       *
87       * @return true if the parameter existed and has been removed, false else.
88       */
89      boolean removeParameter(String name);
90  
91      /**
92       * Returns a {@link Long} parameter value with the given name.
93       * If the parameter is not explicitly set, the default value is returned.
94       *
95       * @param name the parent name.
96       * @param defaultValue the default value.
97       *
98       * @return a {@link Long} that represents the value of the parameter.
99       *
100      * @see #setLongParameter(String, long)
101      */
102     long getLongParameter(String name, long defaultValue);
103 
104     /**
105      * Assigns a {@link Long} to the parameter with the given name
106      *
107      * @param name parameter name
108      * @param value parameter value
109      */
110     HttpParams setLongParameter(String name, long value);
111 
112     /**
113      * Returns an {@link Integer} parameter value with the given name.
114      * If the parameter is not explicitly set, the default value is returned.
115      *
116      * @param name the parent name.
117      * @param defaultValue the default value.
118      *
119      * @return a {@link Integer} that represents the value of the parameter.
120      *
121      * @see #setIntParameter(String, int)
122      */
123     int getIntParameter(String name, int defaultValue);
124 
125     /**
126      * Assigns an {@link Integer} to the parameter with the given name
127      *
128      * @param name parameter name
129      * @param value parameter value
130      */
131     HttpParams setIntParameter(String name, int value);
132 
133     /**
134      * Returns a {@link Double} parameter value with the given name.
135      * If the parameter is not explicitly set, the default value is returned.
136      *
137      * @param name the parent name.
138      * @param defaultValue the default value.
139      *
140      * @return a {@link Double} that represents the value of the parameter.
141      *
142      * @see #setDoubleParameter(String, double)
143      */
144     double getDoubleParameter(String name, double defaultValue);
145 
146     /**
147      * Assigns a {@link Double} to the parameter with the given name
148      *
149      * @param name parameter name
150      * @param value parameter value
151      */
152     HttpParams setDoubleParameter(String name, double value);
153 
154     /**
155      * Returns a {@link Boolean} parameter value with the given name.
156      * If the parameter is not explicitly set, the default value is returned.
157      *
158      * @param name the parent name.
159      * @param defaultValue the default value.
160      *
161      * @return a {@link Boolean} that represents the value of the parameter.
162      *
163      * @see #setBooleanParameter(String, boolean)
164      */
165     boolean getBooleanParameter(String name, boolean defaultValue);
166 
167     /**
168      * Assigns a {@link Boolean} to the parameter with the given name
169      *
170      * @param name parameter name
171      * @param value parameter value
172      */
173     HttpParams setBooleanParameter(String name, boolean value);
174 
175     /**
176      * Checks if a boolean parameter is set to <code>true</code>.
177      *
178      * @param name parameter name
179      *
180      * @return <tt>true</tt> if the parameter is set to value <tt>true</tt>,
181      *         <tt>false</tt> if it is not set or set to <code>false</code>
182      */
183     boolean isParameterTrue(String name);
184 
185     /**
186      * Checks if a boolean parameter is not set or <code>false</code>.
187      *
188      * @param name parameter name
189      *
190      * @return <tt>true</tt> if the parameter is either not set or
191      *         set to value <tt>false</tt>,
192      *         <tt>false</tt> if it is set to <code>true</code>
193      */
194     boolean isParameterFalse(String name);
195 
196 }