KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > servlet > 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 JavaDoc;
20 import java.io.IOException JavaDoc;
21 import java.util.Enumeration JavaDoc;
22 import java.util.Locale JavaDoc;
23 import java.util.Map JavaDoc;
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 JavaDoc getAttribute(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc env) throws java.io.UnsupportedEncodingException JavaDoc;
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 JavaDoc 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 JavaDoc getInputStream() throws IOException JavaDoc;
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 JavaDoc getParameter(String JavaDoc 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 JavaDoc 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 JavaDoc[] getParameterValues(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getReader() throws IOException JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc name, Object JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getRequestDispatcher(String JavaDoc 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 JavaDoc getRealPath(String JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags