001: /*
002: * Copyright (c) 1998-2008 Caucho Technology -- all rights reserved
003: *
004: * This file is part of Resin(R) Open Source
005: *
006: * Each copy or derived work must preserve the copyright notice and this
007: * notice unmodified.
008: *
009: * Resin Open Source is free software; you can redistribute it and/or modify
010: * it under the terms of the GNU General Public License as published by
011: * the Free Software Foundation; either version 2 of the License, or
012: * (at your option) any later version.
013: *
014: * Resin Open Source is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
017: * of NON-INFRINGEMENT. See the GNU General Public License for more
018: * details.
019: *
020: * You should have received a copy of the GNU General Public License
021: * along with Resin Open Source; if not, write to the
022: *
023: * Free Software Foundation, Inc.
024: * 59 Temple Place, Suite 330
025: * Boston, MA 02111-1307 USA
026: *
027: * @author Scott Ferguson
028: */
029:
030: package javax.servlet.http;
031:
032: import javax.servlet.ServletRequest;
033: import java.security.Principal;
034: import java.util.Enumeration;
035:
036: /**
037: * HttpServletRequest encapsulates client request data.
038: *
039: * <h4>URI</h4>
040: *
041: * The servlet engine splits the URI into three useful
042: * sections: the context path (application prefix), the servlet path,
043: * and the path info.
044: *
045: * <p>For example, given an application prefix of '/myapp', the api
046: * <code>/myapp/dir/test.jsp/data</code> will be split as follows:
047: *
048: * <table>
049: * <tr><td>/myapp/dir/test.jsp/data<td>getRequestURI()
050: * <tr><td>/myapp<td>getContextPath()
051: * <tr><td>/dir/test.jsp<td>getServletPath()
052: * <tr><td>/data<td>getPathInfo()
053: * </table>
054: *
055: * <h4>Useful headers</h4>
056: *
057: * <table>
058: * <tr><td>User-Agent<td>String describing the browser's version
059: * </table>
060: *
061: * <h4>CGI equivalents</h4>
062: *
063: * <table>
064: * <tr><td>AUTH_TYPE<td>getAuthType()
065: * <tr><td>CONTENT_TYPE<td>getContentType()
066: * <tr><td>CONTENT_LENGTH<td>getContentLength()
067: * <tr><td>PATH_INFO<td>getPathInfo()
068: * <tr><td>PATH_TRANSLATED<td>getPathTranslated()
069: * <tr><td>QUERY_STRING<td>getQueryString()
070: * <tr><td>REMOTE_ADDR<td>getRemoteAddr()
071: * <tr><td>REMOTE_HOST<td>getRemoteHost()
072: * <tr><td>REMOTE_USER<td>getRemoteUser()
073: * <tr><td>REQUEST_METHOD<td>getMethod()
074: * <tr><td>SCRIPT_NAME<td>getServletPath()
075: * <tr><td>SERVER_NAME<td>getServerName()
076: * <tr><td>SERVER_PROTOCOL<td>getProtocol()
077: * <tr><td>SERVER_PORT<td>getServerPort()
078: * </table>
079: *
080: * <h4>Form data</h4>
081: *
082: * For form data, see <code>ServletRequest.getParameter()</code>
083: */
084:
085: public interface HttpServletRequest extends ServletRequest {
086: /**
087: * String identifier for basic authentication. Value "BASIC".
088: */
089: public final static String BASIC_AUTH = "BASIC";
090: /**
091: * String identifier for client cert authentication. Value "CLIENT_CERT".
092: */
093: public final static String CLIENT_CERT_AUTH = "CLIENT_CERT";
094: /**
095: * String identifier for digest authenciation. Value "DIGEST".
096: */
097: public final static String DIGEST_AUTH = "DIGEST";
098: /**
099: * String identifier for form authenciation. Value "FORM".
100: */
101: public final static String FORM_AUTH = "FORM";
102:
103: /**
104: * Returns the HTTP method, e.g. "GET" or "POST"
105: *
106: * <p/>Equivalent to CGI's <code>REQUEST_METHOD</code>
107: */
108: public String getMethod();
109:
110: /**
111: * Returns the entire request URI
112: */
113: public String getRequestURI();
114:
115: /**
116: * Reconstructs the URL the client used for the request.
117: *
118: * @since Servlet 2.3
119: */
120: public StringBuffer getRequestURL();
121:
122: /**
123: * Returns the part of the URI corresponding to the application's
124: * prefix. The first part of the URI selects applications
125: * (ServletContexts).
126: *
127: * <p><code>getContextPath()</code> is /myapp for the uri
128: * /myapp/servlet/Hello,
129: */
130: public String getContextPath();
131:
132: /**
133: * Returns the URI part corresponding to the selected servlet.
134: * The URI is relative to the application.
135: *
136: * <p/>Corresponds to CGI's <code>SCRIPT_NAME</code>
137: *
138: * <code>getServletPath()</code> is /servlet/Hello for the uri
139: * /myapp/servlet/Hello/foo.
140: *
141: * <code>getServletPath()</code> is /dir/hello.jsp
142: * for the uri /myapp/dir/hello.jsp/foo,
143: */
144: public String getServletPath();
145:
146: /**
147: * Returns the URI part after the selected servlet and null if there
148: * is no suffix.
149: *
150: * <p/>Corresponds to CGI's <code>PATH_INFO</code>
151: *
152: * <p><code>getPathInfo()</code> is /foo for
153: * the uri /myapp/servlet/Hello/foo.
154: *
155: * <code>getPathInfo()</code> is /hello.jsp for for the uri
156: * /myapp/dir/hello.jsp/foo.
157: */
158: public String getPathInfo();
159:
160: /**
161: * Returns the physical path name for the path info.
162: *
163: * <p/>Corresponds to CGI's <code>PATH_TRANSLATED</code>
164: *
165: * @return null if there is no path info.
166: */
167: public String getPathTranslated();
168:
169: /**
170: * Returns the request's query string. Form based servlets will use
171: * <code>ServletRequest.getParameter()</code> to decode the form values.
172: *
173: * <p/>Corresponds to CGI's <code>PATH_TRANSLATED</code>
174: */
175: public String getQueryString();
176:
177: /**
178: * Returns the first value for a request header.
179: *
180: * <p/>Corresponds to CGI's <code>HTTP_*</code>
181: *
182: * <code><pre>
183: * String userAgent = request.getHeader("User-Agent");
184: * </pre></code>
185: *
186: * @param name the header name
187: * @return the header value
188: */
189: public String getHeader(String name);
190:
191: /**
192: * Returns all the values for a request header. In some rare cases,
193: * like cookies, browsers may return multiple headers.
194: *
195: * @param name the header name
196: * @return an enumeration of the header values.
197: */
198: public Enumeration getHeaders(String name);
199:
200: /**
201: * Returns an enumeration of all headers sent by the client.
202: */
203: public Enumeration getHeaderNames();
204:
205: /**
206: * Converts a header value to an integer.
207: *
208: * @param name the header name
209: * @return the header value converted to an integer
210: */
211: public int getIntHeader(String name);
212:
213: /**
214: * Converts a date header to milliseconds since the epoch.
215: *
216: * <pre><code>
217: * long mod = request.getDateHeader("If-Modified-Since");
218: * </code></pre>
219: *
220: * @param name the header name
221: * @return the header value converted to an date
222: */
223: public long getDateHeader(String name);
224:
225: /**
226: * Returns an array of all cookies sent by the client.
227: */
228: public Cookie[] getCookies();
229:
230: /**
231: * Returns a session. If no session exists and create is true, then
232: * create a new session, otherwise return null.
233: *
234: * @param create If true, then create a new session if none exists.
235: */
236: public HttpSession getSession(boolean create);
237:
238: /**
239: * Returns the current session, creating one if necessary.
240: * Sessions are a convenience for keeping user state
241: * across requests.
242: */
243: public HttpSession getSession();
244:
245: /**
246: * Returns the session id. Sessions are a convenience for keeping
247: * user state across requests.
248: *
249: * <p/>The session id is the value of the JSESSION cookie.
250: */
251: public String getRequestedSessionId();
252:
253: /**
254: * Returns true if the session is valid.
255: */
256: public boolean isRequestedSessionIdValid();
257:
258: /**
259: * Returns true if the session came from a cookie.
260: */
261: public boolean isRequestedSessionIdFromCookie();
262:
263: /**
264: * Returns true if the session came URL-encoding.
265: */
266: public boolean isRequestedSessionIdFromURL();
267:
268: /**
269: * Returns the auth type, i.e. BASIC, CLIENT-CERT, DIGEST, or FORM.
270: */
271: public String getAuthType();
272:
273: /**
274: * Returns the remote user if authenticated.
275: */
276: public String getRemoteUser();
277:
278: /**
279: * Returns true if the user is in the given role.
280: */
281: public boolean isUserInRole(String role);
282:
283: /**
284: * Returns the equivalent principal object for the authenticated user.
285: */
286: public Principal getUserPrincipal();
287:
288: /**
289: * @deprecated
290: */
291: public boolean isRequestedSessionIdFromUrl();
292: }
|