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