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