001 /*
002 * Copyright 2004 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.servlet;
017
018 import java.io.BufferedReader;
019 import java.io.IOException;
020 import java.util.Enumeration;
021 import java.util.Locale;
022 import java.util.Map;
023
024
025
026 /**
027 * Defines an object to provide client request information to a servlet. The
028 * servlet container creates a <code>ServletRequest</code> object and passes
029 * it as an argument to the servlet's <code>service</code> method.
030 *
031 * <p>A <code>ServletRequest</code> object provides data including
032 * parameter name and values, attributes, and an input stream.
033 * Interfaces that extend <code>ServletRequest</code> can provide
034 * additional protocol-specific data (for example, HTTP data is
035 * provided by {@link javax.servlet.http.HttpServletRequest}.
036 *
037 * @author Various
038 * @version $Version$
039 *
040 * @see javax.servlet.http.HttpServletRequest
041 *
042 */
043
044 public interface ServletRequest {
045
046
047
048
049 /**
050 *
051 * Returns the value of the named attribute as an <code>Object</code>,
052 * or <code>null</code> if no attribute of the given name exists.
053 *
054 * <p> Attributes can be set two ways. The servlet container may set
055 * attributes to make available custom information about a request.
056 * For example, for requests made using HTTPS, the attribute
057 * <code>javax.servlet.request.X509Certificate</code> can be used to
058 * retrieve information on the certificate of the client. Attributes
059 * can also be set programatically using
060 * {@link ServletRequest#setAttribute}. This allows information to be
061 * embedded into a request before a {@link RequestDispatcher} call.
062 *
063 * <p>Attribute names should follow the same conventions as package
064 * names. This specification reserves names matching <code>java.*</code>,
065 * <code>javax.*</code>, and <code>sun.*</code>.
066 *
067 * @param name a <code>String</code> specifying the name of
068 * the attribute
069 *
070 * @return an <code>Object</code> containing the value
071 * of the attribute, or <code>null</code> if
072 * the attribute does not exist
073 *
074 */
075
076 public Object getAttribute(String name);
077
078
079
080 /**
081 * Returns an <code>Enumeration</code> containing the
082 * names of the attributes available to this request.
083 * This method returns an empty <code>Enumeration</code>
084 * if the request has no attributes available to it.
085 *
086 *
087 * @return an <code>Enumeration</code> of strings
088 * containing the names
089 * of the request's attributes
090 *
091 */
092
093 public Enumeration getAttributeNames();
094
095
096
097
098 /**
099 * 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