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