ServletRequest


1   /*
2   * Licensed to the Apache Software Foundation (ASF) under one or more
3   * contributor license agreements.  See the NOTICE file distributed with
4   * this work for additional information regarding copyright ownership.
5   * The ASF licenses this file to You under the Apache License, Version 2.0
6   * (the "License"); you may not use this file except in compliance with
7   * the License.  You may obtain a copy of the License at
8   *
9   *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17  package javax.servlet;
18  
19  import java.io.BufferedReader  ;
20  import java.io.IOException  ;
21  import java.util.Enumeration  ;
22  import java.util.Locale  ;
23  import java.util.Map  ;
24  
25  
26  
27  /**
28   * Defines an object to provide client request information to a servlet.  The
29   * servlet container creates a <code>ServletRequest</code> object and passes
30   * it as an argument to the servlet's <code>service</code> method.
31   *
32   * <p>A <code>ServletRequest</code> object provides data including
33   * parameter name and values, attributes, and an input stream.
34   * Interfaces that extend <code>ServletRequest</code> can provide
35   * additional protocol-specific data (for example, HTTP data is
36   * provided by {@link javax.servlet.http.HttpServletRequest}.
37   * 
38   * @author  Various
39   * @version     $Version$
40   *
41   * @see     javax.servlet.http.HttpServletRequest
42   *
43   */
44  
45  public interface ServletRequest {
46  
47  
48  
49  
50      /**
51       *
52       * Returns the value of the named attribute as an <code>Object</code>,
53       * or <code>null</code> if no attribute of the given name exists. 
54       *
55       * <p> Attributes can be set two ways.  The servlet container may set
56       * attributes to make available custom information about a request.
57       * For example, for requests made using HTTPS, the attribute
58       * <code>javax.servlet.request.X509Certificate</code> can be used to
59       * retrieve information on the certificate of the client.  Attributes
60       * can also be set programatically using 
61       * {@link ServletRequest#setAttribute}.  This allows information to be
62       * embedded into a request before a {@link RequestDispatcher} call.
63       *
64       * <p>Attribute names should follow the same conventions as package
65       * names. This specification reserves names matching <code>java.*</code>,
66       * <code>javax.*</code>, and <code>sun.*</code>. 
67       *
68       * @param name  a <code>String</code> specifying the name of 
69       *          the attribute
70       *
71       * @return      an <code>Object</code> containing the value 
72       *          of the attribute, or <code>null</code> if
73       *          the attribute does not exist
74       *
75       */
76  
77      public Object   getAttribute(String   name);
78      
79      
80  
81      /**
82       * Returns an <code>Enumeration</code> containing the
83       * names of the attributes available to this request. 
84       * This method returns an empty <code>Enumeration</code>
85       * if the request has no attributes available to it.
86       * 
87       *
88       * @return      an <code>Enumeration</code> of strings 
89       *          containing the names 
90       *          of the request's attributes
91       *
92       */
93  
94      public Enumeration   getAttributeNames();
95      
96      
97      
98      
99      /**
100      * Returns the name of the character encoding used in the body of this
101      * request. This method returns <code>null</code> if the request
102      * does not specify a character encoding
103      * 
104      *
105      * @return      a <code>String</code> containing the name of 
106      *          the character encoding, or <code>null</code>
107      *          if the request does not specify a character encoding
108      *
109      */
110 
111     public String   getCharacterEncoding();
112 
113  /**
114      * Overrides the name of the character encoding used in the body of this
115      * request. This method must be called prior to reading request parameters
116      * or reading input using getReader().
117      * 
118      *
119      * @param env   a <code>String</code> containing the name of 
120      *          the character encoding.
121      * @throws      java.io.UnsupportedEncodingException if this is not a valid encoding
122      */
123 
124     public void setCharacterEncoding(String   env) throws java.io.UnsupportedEncodingException  ;
125 
126     
127     
128     
129     
130     /**
131      * Returns the length, in bytes, of the request body 
132      * and made available by the input stream, or -1 if the
133      * length is not known. For HTTP servlets, same as the value
134      * of the CGI variable CONTENT_LENGTH.
135      *
136      * @return      an integer containing the length of the 
137      *          request body or -1 if the length is not known
138      *
139      */
140 
141     public int getContentLength();
142     
143     
144     
145 
146     /**
147      * Returns the MIME type of the body of the request, or 
148      * <code>null</code> if the type is not known. For HTTP servlets, 
149      * same as the value of the CGI variable CONTENT_TYPE.
150      *
151      * @return      a <code>String</code> containing the name 
152      *          of the MIME type of 
153      *          the request, or null if the type is not known
154      *
155      */
156 
157     public String   getContentType();
158     
159     
160     
161 
162     /**
163      * Retrieves the body of the request as binary data using
164      * a {@link ServletInputStream}.  Either this method or 
165      * {@link #getReader} may be called to read the body, not both.
166      *
167      * @return          a {@link ServletInputStream} object containing
168      *              the body of the request
169      *
170      * @exception IllegalStateException  if the {@link #getReader} method
171      *                   has already been called for this request
172      *
173      * @exception IOException       if an input or output exception occurred
174      *
175      */
176 
177     public ServletInputStream   getInputStream() throws IOException  ; 
178      
179     
180     
181 
182     /**
183      * Returns the value of a request parameter as a <code>String</code>,
184      * or <code>null</code> if the parameter does not exist. Request parameters
185      * are extra information sent with the request.  For HTTP servlets,
186      * parameters are contained in the query string or posted form data.
187      *
188      * <p>You should only use this method when you are sure the
189      * parameter has only one value. If the parameter might have
190      * more than one value, use {@link #getParameterValues}.
191      *
192      * <p>If you use this method with a multivalued
193      * parameter, the value returned is equal to the first value
194      * in the array returned by <code>getParameterValues</code>.
195      *
196      * <p>If the parameter data was sent in the request body, such as occurs
197      * with an HTTP POST request, then reading the body directly via {@link
198      * #getInputStream} or {@link #getReader} can interfere
199      * with the execution of this method.
200      *
201      * @param name  a <code>String</code> specifying the 
202      *          name of the parameter
203      *
204      * @return      a <code>String</code> representing the 
205      *          single value of the parameter
206      *
207      * @see         #getParameterValues
208      *
209      */
210 
211     public String   getParameter(String   name);
212     
213     
214     
215 
216     /**
217      *
218      * Returns an <code>Enumeration</code> of <code>String</code>
219      * objects containing the names of the parameters contained
220      * in this request. If the request has 
221      * no parameters, the method returns an 
222      * empty <code>Enumeration</code>. 
223      *
224      * @return      an <code>Enumeration</code> of <code>String</code>
225      *          objects, each <code>String</code> containing
226      *          the name of a request parameter; or an 
227      *          empty <code>Enumeration</code> if the
228      *          request has no parameters
229      *
230      */
231      
232     public Enumeration   getParameterNames();
233     
234     
235     
236 
237     /**
238      * Returns an array of <code>String</code> objects containing 
239      * all of the values the given request parameter has, or 
240      * <code>null</code> if the parameter does not exist.
241      *
242      * <p>If the parameter has a single value, the array has a length
243      * of 1.
244      *
245      * @param name  a <code>String</code> containing the name of 
246      *          the parameter whose value is requested
247      *
248      * @return      an array of <code>String</code> objects 
249      *          containing the parameter's values
250      *
251      * @see     #getParameter
252      *
253      */
254 
255     public String  [] getParameterValues(String   name);
256  
257     /** Returns a java.util.Map of the parameters of this request.
258      * Request parameters
259      * are extra information sent with the request.  For HTTP servlets,
260      * parameters are contained in the query string or posted form data.
261      *
262      * @return an immutable java.util.Map containing parameter names as 
263      * keys and parameter values as map values. The keys in the parameter
264      * map are of type String. The values in the parameter map are of type
265      * String array.
266      *
267      */
268 
269     public Map   getParameterMap();
270     
271     
272 
273     /**
274      * Returns the name and version of the protocol the request uses
275      * in the form <i>protocol/majorVersion.minorVersion</i>, for 
276      * example, HTTP/1.1. For HTTP servlets, the value
277      * returned is the same as the value of the CGI variable 
278      * <code>SERVER_PROTOCOL</code>.
279      *
280      * @return      a <code>String</code> containing the protocol 
281      *          name and version number
282      *
283      */
284     
285     public String   getProtocol();
286     
287     
288     
289 
290     /**
291      * Returns the name of the scheme used to make this request, 
292      * for example,
293      * <code>http</code>, <code>https</code>, or <code>ftp</code>.
294      * Different schemes have different rules for constructing URLs,
295      * as noted in RFC 1738.
296      *
297      * @return      a <code>String</code> containing the name 
298      *          of the scheme used to make this request
299      *
300      */
301 
302     public String   getScheme();
303     
304     
305     
306 
307     /**
308      * Returns the host name of the server to which the request was sent.
309      * It is the value of the part before ":" in the <code>Host</code>
310      * header value, if any, or the resolved server name, or the server IP address.
311      *
312      * @return      a <code>String</code> containing the name 
313      *          of the server
314      */
315 
316     public String   getServerName();
317     
318     
319     
320 
321     /**
322      * Returns the port number to which the request was sent.
323      * It is the value of the part after ":" in the <code>Host</code>
324      * header value, if any, or the server port where the client connection
325      * was accepted on.
326      *
327      * @return      an integer specifying the port number
328      *
329      */
330 
331     public int getServerPort();
332     
333     
334     
335     /**
336      * Retrieves the body of the request as character data using
337      * a <code>BufferedReader</code>.  The reader translates the character
338      * data according to the character encoding used on the body.
339      * Either this method or {@link #getInputStream} may be called to read the
340      * body, not both.
341      * 
342      *
343      * @return                  a <code>BufferedReader</code>
344      *                      containing the body of the request  
345      *
346      * @exception UnsupportedEncodingException  if the character set encoding
347      *                      used is not supported and the 
348      *                      text cannot be decoded
349      *
350      * @exception IllegalStateException     if {@link #getInputStream} method
351      *                      has been called on this request
352      *
353      * @exception IOException           if an input or output exception occurred
354      *
355      * @see                     #getInputStream
356      *
357      */
358 
359     public BufferedReader   getReader() throws IOException  ;
360     
361     
362     
363 
364     /**
365      * Returns the Internet Protocol (IP) address of the client 
366      * or last proxy that sent the request.
367      * For HTTP servlets, same as the value of the 
368      * CGI variable <code>REMOTE_ADDR</code>.
369      *
370      * @return      a <code>String</code> containing the 
371      *          IP address of the client that sent the request
372      *
373      */
374     
375     public String   getRemoteAddr();
376     
377     
378     
379 
380     /**
381      * Returns the fully qualified name of the client
382      * or the last proxy that sent the request.
383      * If the engine cannot or chooses not to resolve the hostname 
384      * (to improve performance), this method returns the dotted-string form of 
385      * the IP address. For HTTP servlets, same as the value of the CGI variable 
386      * <code>REMOTE_HOST</code>.
387      *
388      * @return      a <code>String</code> containing the fully 
389      *          qualified name of the client
390      *
391      */
392 
393     public String   getRemoteHost();
394     
395     
396     
397 
398     /**
399      *
400      * Stores an attribute in this request.
401      * Attributes are reset between requests.  This method is most
402      * often used in conjunction with {@link RequestDispatcher}.
403      *
404      * <p>Attribute names should follow the same conventions as
405      * package names. Names beginning with <code>java.*</code>,
406      * <code>javax.*</code>, and <code>com.sun.*</code>, are
407      * reserved for use by Sun Microsystems.
408      *<br> If the object passed in is null, the effect is the same as
409      * calling {@link #removeAttribute}.
410      * <br> It is warned that when the request is dispatched from the
411      * servlet resides in a different web application by
412      * <code>RequestDispatcher</code>, the object set by this method
413      * may not be correctly retrieved in the caller servlet.
414      *
415      *
416      * @param name          a <code>String</code> specifying 
417      *                  the name of the attribute
418      *
419      * @param o             the <code>Object</code> to be stored
420      *
421      */
422 
423     public void setAttribute(String   name, Object   o);
424     
425     
426     
427 
428     /**
429      *
430      * Removes an attribute from this request.  This method is not
431      * generally needed as attributes only persist as long as the request
432      * is being handled.
433      *
434      * <p>Attribute names should follow the same conventions as
435      * package names. Names beginning with <code>java.*</code>,
436      * <code>javax.*</code>, and <code>com.sun.*</code>, are
437      * reserved for use by Sun Microsystems.
438      *
439      *
440      * @param name          a <code>String</code> specifying 
441      *                  the name of the attribute to remove
442      *
443      */
444 
445     public void removeAttribute(String   name);
446     
447     
448     
449 
450     /**
451      *
452      * Returns the preferred <code>Locale</code> that the client will 
453      * accept content in, based on the Accept-Language header.
454      * If the client request doesn't provide an Accept-Language header,
455      * this method returns the default locale for the server.
456      *
457      *
458      * @return      the preferred <code>Locale</code> for the client
459      *
460      */
461 
462     public Locale   getLocale();
463     
464     
465     
466 
467     /**
468      *
469      * Returns an <code>Enumeration</code> of <code>Locale</code> objects
470      * indicating, in decreasing order starting with the preferred locale, the
471      * locales that are acceptable to the client based on the Accept-Language
472      * header.
473      * If the client request doesn't provide an Accept-Language header,
474      * this method returns an <code>Enumeration</code> containing one 
475      * <code>Locale</code>, the default locale for the server.
476      *
477      *
478      * @return      an <code>Enumeration</code> of preferred 
479      *                  <code>Locale</code> objects for the client
480      *
481      */
482 
483     public Enumeration   getLocales();
484     
485     
486     
487 
488     /**
489      *
490      * Returns a boolean indicating whether this request was made using a
491      * secure channel, such as HTTPS.
492      *
493      *
494      * @return      a boolean indicating if the request was made using a
495      *                  secure channel
496      *
497      */
498 
499     public boolean isSecure();
500     
501     
502     
503 
504     /**
505      *
506      * Returns a {@link RequestDispatcher} object that acts as a wrapper for
507      * the resource located at the given path.  
508      * A <code>RequestDispatcher</code> object can be used to forward
509      * a request to the resource or to include the resource in a response.
510      * The resource can be dynamic or static.
511      *
512      * <p>The pathname specified may be relative, although it cannot extend
513      * outside the current servlet context.  If the path begins with 
514      * a "/" it is interpreted as relative to the current context root.  
515      * This method returns <code>null</code> if the servlet container
516      * cannot return a <code>RequestDispatcher</code>.
517      *
518      * <p>The difference between this method and {@link
519      * ServletContext#getRequestDispatcher} is that this method can take a
520      * relative path.
521      *
522      * @param path      a <code>String</code> specifying the pathname
523      *                  to the resource. If it is relative, it must be
524      *                  relative against the current servlet.
525      *
526      * @return          a <code>RequestDispatcher</code> object
527      *                  that acts as a wrapper for the resource
528      *                  at the specified path, or <code>null</code>
529      *                  if the servlet container cannot return a
530      *                  <code>RequestDispatcher</code>
531      *
532      * @see             RequestDispatcher
533      * @see             ServletContext#getRequestDispatcher
534      *
535      */
536 
537     public RequestDispatcher   getRequestDispatcher(String   path);
538     
539     
540     
541 
542     /**
543      * 
544      * @deprecated  As of Version 2.1 of the Java Servlet API,
545      *          use {@link ServletContext#getRealPath} instead.
546      *
547      */
548 
549     public String   getRealPath(String   path);
550     
551     
552     /**
553      * Returns the Internet Protocol (IP) source port of the client
554      * or last proxy that sent the request.
555      *
556      * @return  an integer specifying the port number
557      *
558      * @since 2.4
559      */    
560     public int getRemotePort();
561 
562 
563     /**
564      * Returns the host name of the Internet Protocol (IP) interface on
565      * which the request was received.
566      *
567      * @return  a <code>String</code> containing the host
568      *      name of the IP on which the request was received.
569      *
570      * @since 2.4
571      */
572     public String   getLocalName();
573 
574     /**
575      * Returns the Internet Protocol (IP) address of the interface on
576      * which the request  was received.
577      *
578      * @return  a <code>String</code> containing the
579      *      IP address on which the request was received. 
580      *
581      * @since 2.4
582      *
583      */       
584     public String   getLocalAddr();
585 
586 
587     /**
588      * Returns the Internet Protocol (IP) port number of the interface
589      * on which the request was received.
590      *
591      * @return an integer specifying the port number
592      *
593      * @since 2.4
594      */
595     public int getLocalPort();
596 
597 }
598 
599
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags