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