View Javadoc

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