1
2
3
4
5
6
7
8
9
10
11
12
13
14
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