001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.servlet;
021
022 import java.io.BufferedReader;
023 import java.io.IOException;
024 import java.util.Enumeration;
025 import java.util.Locale;
026 import java.util.Map;
027
028
029
030 /**
031 * Defines an object to provide client request information to a servlet. The
032 * servlet container creates a <code>ServletRequest</code> object and passes
033 * it as an argument to the servlet's <code>service</code> method.
034 *
035 * <p>A <code>ServletRequest</code> object provides data including
036 * parameter name and values, attributes, and an input stream.
037 * Interfaces that extend <code>ServletRequest</code> can provide
038 * additional protocol-specific data (for example, HTTP data is
039 * provided by {@link javax.servlet.http.HttpServletRequest}.
040 *
041 * @author Various
042 * @version $Version$
043 *
044 * @see javax.servlet.http.HttpServletRequest
045 *
046 */
047
048 public interface ServletRequest {
049
050
051
052
053 /**
054 *
055 * Returns the value of the named attribute as an <code>Object</code>,
056 * or <code>null</code> if no attribute of the given name exists.
057 *
058 * <p> Attributes can be set two ways. The servlet container may set
059 * attributes to make available custom information about a request.
060 * For example, for requests made using HTTPS, the attribute
061 * <code>javax.servlet.request.X509Certificate</code> can be used to
062 * retrieve information on the certificate of the client. Attributes
063 * can also be set programatically using
064 * {@link ServletRequest#setAttribute}. This allows information to be
065 * embedded into a request before a {@link RequestDispatcher} call.
066 *
067 * <p>Attribute names should follow the same conventions as package
068 * names. This specification reserves names matching <code>java.*</code>,
069 * <code>javax.*</code>, and <code>sun.*</code>.
070 *
071 * @param name a <code>String</code> specifying the name of
072 * the attribute
073 *
074 * @return an <code>Object</code> containing the value
075 * of the attribute, or <code>null</code> if
076 * the attribute does not exist
077 *
078 */
079
080 public Object getAttribute(String name);
081
082
083
084 /**
085 * Returns an <code>Enumeration</code> containing the
086 * names of the attributes available to this request.
087 * This method returns an empty <code>Enumeration</code>
088 * if the request has no attributes available to it.
089 *
090 *
091 * @return an <code>Enumeration</code> of strings
092 * containing the names
093 * of the request's attributes
094 *
095 */
096
097 public Enumeration getAttributeNames();
098
099
100
101
102 /**
103 * Returns the name of the character encoding used in the body of this
104 * request. This method returns <code>null</code> if the request
105 * does not specify a character encoding
106 *
107 *
108 * @return a <code>String</code> containing the name of
109 * the character encoding, or <code>null</code>
110 * if the request does not specify a character encoding
111 *
112 */
113
114 public String getCharacterEncoding();
115
116 /**
117 * Overrides the name of the character encoding used in the body of this
118 * request. This method must be called prior to reading request parameters
119 * or reading input using getReader().
120 *
121 *
122 * @param env a <code>String</code> containing the name of
123 * the character encoding.
124 * @throws java.io.UnsupportedEncodingException if this is not a valid encoding
125 */
126
127 public void setCharacterEncoding(String env) throws java.io.UnsupportedEncodingException;
128
129
130
131
132
133 /**
134 * Returns the length, in bytes, of the request body
135 * and made available by the input stream, or -1 if the
136 * length is not known. For HTTP servlets, same as the value
137 * of the CGI variable CONTENT_LENGTH.
138 *
139 * @return an integer containing the length of the
140 * request body or -1 if the length is not known
141 *
142 */
143
144 public int getContentLength();
145
146
147
148
149 /**
150 * Returns the MIME type of the body of the request, or
151 * <code>null</code> if the type is not known. For HTTP servlets,
152 * same as the value of the CGI variable CONTENT_TYPE.
153 *
154 * @return a <code>String</code> containing the name
155 * of the MIME type of
156 * the request, or null if the type is not known
157 *
158 */
159
160 public String getContentType();
161
162
163
164
165 /**
166 * Retrieves the body of the request as binary data using
167 * a {@link ServletInputStream}. Either this method or
168 * {@link #getReader} may be called to read the body, not both.
169 *
170 * @return a {@link ServletInputStream} object containing
171 * the body of the request
172 *
173 * @exception IllegalStateException if the {@link #getReader} method
174 * has already been called for this request
175 *
176 * @exception IOException if an input or output exception occurred
177 *
178 */
179
180 public ServletInputStream getInputStream() throws IOException;
181
182
183
184
185 /**
186 * Returns the value of a request parameter as a <code>String</code>,
187 * or <code>null</code> if the parameter does not exist. Request parameters
188 * are extra information sent with the request. For HTTP servlets,
189 * parameters are contained in the query string or posted form data.
190 *
191 * <p>You should only use this method when you are sure the
192 * parameter has only one value. If the parameter might have
193 * more than one value, use {@link #getParameterValues}.
194 *
195 * <p>If you use this method with a multivalued
196 * parameter, the value returned is equal to the first value
197 * in the array returned by <code>getParameterValues</code>.
198 *
199 * <p>If the parameter data was sent in the request body, such as occurs
200 * with an HTTP POST request, then reading the body directly via {@link
201 * #getInputStream} or {@link #getReader} can interfere
202 * with the execution of this method.
203 *
204 * @param name a <code>String</code> specifying the
205 * name of the parameter
206 *
207 * @return a <code>String</code> representing the
208 * single value of the parameter
209 *
210 * @see #getParameterValues
211 *
212 */
213
214 public String getParameter(String name);
215
216
217
218
219 /**
220 *
221 * Returns an <code>Enumeration</code> of <code>String</code>
222 * objects containing the names of the parameters contained
223 * in this request. If the request has
224 * no parameters, the method returns an
225 * empty <code>Enumeration</code>.
226 *
227 * @return an <code>Enumeration</code> of <code>String</code>
228 * objects, each <code>String</code> containing
229 * the name of a request parameter; or an
230 * empty <code>Enumeration</code> if the
231 * request has no parameters
232 *
233 */
234
235 public Enumeration getParameterNames();
236
237
238
239
240 /**
241 * Returns an array of <code>String</code> objects containing
242 * all of the values the given request parameter has, or
243 * <code>null</code> if the parameter does not exist.
244 *
245 * <p>If the parameter has a single value, the array has a length
246 * of 1.
247 *
248 * @param name a <code>String</code> containing the name of
249 * the parameter whose value is requested
250 *
251 * @return an array of <code>String</code> objects
252 * containing the parameter's values
253 *
254 * @see #getParameter
255 *
256 */
257
258 public String[] getParameterValues(String name);
259
260 /** Returns a java.util.Map of the parameters of this request.
261 * Request parameters
262 * are extra information sent with the request. For HTTP servlets,
263 * parameters are contained in the query string or posted form data.
264 *
265 * @return an immutable java.util.Map containing parameter names as
266 * keys and parameter values as map values. The keys in the parameter
267 * map are of type String. The values in the parameter map are of type
268 * String array.
269 *
270 */
271
272 public Map getParameterMap();
273
274
275
276 /**
277 * Returns the name and version of the protocol the request uses
278 * in the form <i>protocol/majorVersion.minorVersion</i>, for
279 * example, HTTP/1.1. For HTTP servlets, the value
280 * returned is the same as the value of the CGI variable
281 * <code>SERVER_PROTOCOL</code>.
282 *
283 * @return a <code>String</code> containing the protocol
284 * name and version number
285 *
286 */
287
288 public String getProtocol();
289
290
291
292
293 /**
294 * Returns the name of the scheme used to make this request,
295 * for example,
296 * <code>http</code>, <code>https</code>, or <code>ftp</code>.
297 * Different schemes have different rules for constructing URLs,
298 * as noted in RFC 1738.
299 *
300 * @return a <code>String</code> containing the name
301 * of the scheme used to make this request
302 *
303 */
304
305 public String getScheme();
306
307
308
309
310 /**
311 * Returns the host name of the server to which the request was sent.
312 * It is the value of the part before ":" in the <code>Host</code>
313 * header value, if any, or the resolved server name, or the server IP address.
314 *
315 * @return a <code>String</code> containing the name
316 * of the server
317 */
318
319 public String getServerName();
320
321
322
323
324 /**
325 * Returns the port number to which the request was sent.
326 * It is the value of the part after ":" in the <code>Host</code>
327 * header value, if any, or the server port where the client connection
328 * was accepted on.
329 *
330 * @return an integer specifying the port number
331 *
332 */
333
334 public int getServerPort();
335
336
337
338 /**
339 * Retrieves the body of the request as character data using
340 * a <code>BufferedReader</code>. The reader translates the character
341 * data according to the character encoding used on the body.
342 * Either this method or {@link #getInputStream} may be called to read the
343 * body, not both.
344 *
345 *
346 * @return a <code>BufferedReader</code>
347 * containing the body of the request
348 *
349 * @exception UnsupportedEncodingException if the character set encoding
350 * used is not supported and the
351 * text cannot be decoded
352 *
353 * @exception IllegalStateException if {@link #getInputStream} method
354 * has been called on this request
355 *
356 * @exception IOException if an input or output exception occurred
357 *
358 * @see #getInputStream
359 *
360 */
361
362 public BufferedReader getReader() throws IOException;
363
364
365
366
367 /**
368 * Returns the Internet Protocol (IP) address of the client
369 * or last proxy that sent the request.
370 * For HTTP servlets, same as the value of the
371 * CGI variable <code>REMOTE_ADDR</code>.
372 *
373 * @return a <code>String</code> containing the
374 * IP address of the client that sent the request
375 *
376 */
377
378 public String getRemoteAddr();
379
380
381
382
383 /**
384 * Returns the fully qualified name of the client
385 * or the last proxy that sent the request.
386 * If the engine cannot or chooses not to resolve the hostname
387 * (to improve performance), this method returns the dotted-string form of
388 * the IP address. For HTTP servlets, same as the value of the CGI variable
389 * <code>REMOTE_HOST</code>.
390 *
391 * @return a <code>String</code> containing the fully
392 * qualified name of the client
393 *
394 */
395
396 public String getRemoteHost();
397
398
399
400
401 /**
402 *
403 * Stores an attribute in this request.
404 * Attributes are reset between requests. This method is most
405 * often used in conjunction with {@link RequestDispatcher}.
406 *
407 * <p>Attribute names should follow the same conventions as
408 * package names. Names beginning with <code>java.*</code>,
409 * <code>javax.*</code>, and <code>com.sun.*</code>, are
410 * reserved for use by Sun Microsystems.
411 *<br> If the object passed in is null, the effect is the same as
412 * calling {@link #removeAttribute}.
413 * <br> It is warned that when the request is dispatched from the
414 * servlet resides in a different web application by
415 * <code>RequestDispatcher</code>, the object set by this method
416 * may not be correctly retrieved in the caller servlet.
417 *
418 *
419 * @param name a <code>String</code> specifying
420 * the name of the attribute
421 *
422 * @param o the <code>Object</code> to be stored
423 *
424 */
425
426 public void setAttribute(String name, Object o);
427
428
429
430
431 /**
432 *
433 * Removes an attribute from this request. This method is not
434 * generally needed as attributes only persist as long as the request
435 * is being handled.
436 *
437 * <p>Attribute names should follow the same conventions as
438 * package names. Names beginning with <code>java.*</code>,
439 * <code>javax.*</code>, and <code>com.sun.*</code>, are
440 * reserved for use by Sun Microsystems.
441 *
442 *
443 * @param name a <code>String</code> specifying
444 * the name of the attribute to remove
445 *
446 */
447
448 public void removeAttribute(String name);
449
450
451
452
453 /**
454 *
455 * Returns the preferred <code>Locale</code> that the client will
456 * accept content in, based on the Accept-Language header.
457 * If the client request doesn't provide an Accept-Language header,
458 * this method returns the default locale for the server.
459 *
460 *
461 * @return the preferred <code>Locale</code> for the client
462 *
463 */
464
465 public Locale getLocale();
466
467
468
469
470 /**
471 *
472 * Returns an <code>Enumeration</code> of <code>Locale</code> objects
473 * indicating, in decreasing order starting with the preferred locale, the
474 * locales that are acceptable to the client based on the Accept-Language
475 * header.
476 * If the client request doesn't provide an Accept-Language header,
477 * this method returns an <code>Enumeration</code> containing one
478 * <code>Locale</code>, the default locale for the server.
479 *
480 *
481 * @return an <code>Enumeration</code> of preferred
482 * <code>Locale</code> objects for the client
483 *
484 */
485
486 public Enumeration getLocales();
487
488
489
490
491 /**
492 *
493 * Returns a boolean indicating whether this request was made using a
494 * secure channel, such as HTTPS.
495 *
496 *
497 * @return a boolean indicating if the request was made using a
498 * secure channel
499 *
500 */
501
502 public boolean isSecure();
503
504
505
506
507 /**
508 *
509 * Returns a {@link RequestDispatcher} object that acts as a wrapper for
510 * the resource located at the given path.
511 * A <code>RequestDispatcher</code> object can be used to forward
512 * a request to the resource or to include the resource in a response.
513 * The resource can be dynamic or static.
514 *
515 * <p>The pathname specified may be relative, although it cannot extend
516 * outside the current servlet context. If the path begins with
517 * a "/" it is interpreted as relative to the current context root.
518 * This method returns <code>null</code> if the servlet container
519 * cannot return a <code>RequestDispatcher</code>.
520 *
521 * <p>The difference between this method and {@link
522 * ServletContext#getRequestDispatcher} is that this method can take a
523 * relative path.
524 *
525 * @param path a <code>String</code> specifying the pathname
526 * to the resource. If it is relative, it must be
527 * relative against the current servlet.
528 *
529 * @return a <code>RequestDispatcher</code> object
530 * that acts as a wrapper for the resource
531 * at the specified path, or <code>null</code>
532 * if the servlet container cannot return a
533 * <code>RequestDispatcher</code>
534 *
535 * @see RequestDispatcher
536 * @see ServletContext#getRequestDispatcher
537 *
538 */
539
540 public RequestDispatcher getRequestDispatcher(String path);
541
542
543
544
545 /**
546 *
547 * @deprecated As of Version 2.1 of the Java Servlet API,
548 * use {@link ServletContext#getRealPath} instead.
549 *
550 */
551
552 public String getRealPath(String path);
553
554
555 /**
556 * Returns the Internet Protocol (IP) source port of the client
557 * or last proxy that sent the request.
558 *
559 * @return an integer specifying the port number
560 *
561 * @since 2.4
562 */
563 public int getRemotePort();
564
565
566 /**
567 * Returns the host name of the Internet Protocol (IP) interface on
568 * which the request was received.
569 *
570 * @return a <code>String</code> containing the host
571 * name of the IP on which the request was received.
572 *
573 * @since 2.4
574 */
575 public String getLocalName();
576
577 /**
578 * Returns the Internet Protocol (IP) address of the interface on
579 * which the request was received.
580 *
581 * @return a <code>String</code> containing the
582 * IP address on which the request was received.
583 *
584 * @since 2.4
585 *
586 */
587 public String getLocalAddr();
588
589
590 /**
591 * Returns the Internet Protocol (IP) port number of the interface
592 * on which the request was received.
593 *
594 * @return an integer specifying the port number
595 *
596 * @since 2.4
597 */
598 public int getLocalPort();
599
600 }
601