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;
031:
032: import java.io.BufferedReader;
033: import java.io.IOException;
034: import java.util.Enumeration;
035: import java.util.Locale;
036: import java.util.Map;
037:
038: /**
039: * ServletRequest encapsulates client request data. See HttpServletRequest
040: * for HTTP-specific information.
041: *
042: * <p>Requests have user-defined attributes. Servlets can communicate
043: * to included or forwarded pages using the request attributes. For example,
044: * a servlet may calculate results and place them in the request attributes.
045: * It may then forward the call to a JSP template to format the result.
046: *
047: * <p>Form parameters are retrieved using <code>getParameter</code>
048: */
049: public interface ServletRequest {
050: /**
051: * Returns the prococol, e.g. "HTTP/1.1"
052: */
053: public String getProtocol();
054:
055: /**
056: * Returns the request scheme, e.g. "http"
057: */
058: public String getScheme();
059:
060: /**
061: * Returns the server name handling the request. When using virtual hosts,
062: * this returns the virtual host name, e.g. "vhost1.caucho.com".
063: *
064: * This call returns the host name as the client sees it, which means that
065: * if ipchains, load balancing, or proxying is involved this call returns the
066: * correct call for forming urls, but may not contain the host that Resin is
067: * actually listening on.
068: */
069: public String getServerName();
070:
071: /**
072: * Returns the server port used by the client, e.g. 80.
073: *
074: * This call returns the port number as the client sees it, which means that
075: * if ipchains, load balancing, or proxying is involved this call returns the
076: * correct call for forming urls, but may not return the actual port that
077: * Resin is listening on.
078: *
079: * This call should not be used to test for an ssl connection
080: * (getServerPort() == 443), {@link #isSecure()} is provided for that purpose.
081: */
082: public int getServerPort();
083:
084: /**
085: * Returns the IP address of the remote host, i.e. the client browser.
086: */
087: public String getRemoteAddr();
088:
089: /**
090: * Returns the DNS hostname of the remote host, i.e. the client browser.
091: */
092: public String getRemoteHost();
093:
094: /**
095: * Returns the port of the remote host, i.e. the client browser.
096: *
097: * @since 2.4
098: */
099: public int getRemotePort();
100:
101: /**
102: * This call returns the ip of the host actually used to connect to the Resin
103: * server, which means that if ipchains, load balancing, or proxying is
104: * involved this call <i>does not</i> return the correct host for
105: * forming urls.
106: *
107: * @since 2.4
108: */
109: public String getLocalAddr();
110:
111: /**
112: * Returns the IP address of the local host, i.e. the server.
113: *
114: * This call returns the name of the host actaully used to connect to the
115: * Resin server, which means that if ipchains, load balancing, or proxying
116: * is involved this call <i>does not</i> return the correct host for
117: * forming urls.
118: *
119: * @since 2.4
120: */
121: public String getLocalName();
122:
123: /**
124: * Returns the port of the local host.
125: *
126: * This call returns the port number actually used to connect to the Resin
127: * server, which means that if ipchains, load balancing, or proxying is
128: * involved this call <i>does not</i> return the correct port for
129: * forming urls.
130: *
131: * This call should not be used to test for an ssl connection
132: * (getServerPort() == 443), {@link #isSecure()} is provided for that purpose.
133: *
134: * @since 2.4
135: */
136: public int getLocalPort();
137:
138: /**
139: * Overrides the character encoding specified in the request.
140: * <code>setCharacterEncoding</code> must be called before calling
141: * <code>getReader</code> or reading any parameters.
142: */
143: public void setCharacterEncoding(String encoding)
144: throws java.io.UnsupportedEncodingException;
145:
146: /**
147: * Returns a form parameter. When the form contains several parameters
148: * of the same name, <code>getParameter</code> returns the first.
149: *
150: * <p>For example, calling <code>getParameter("a")</code> with the
151: * the query string <code>a=1&a=2</code> will return "1".
152: *
153: * @param name the form parameter to return
154: * @return the form value or null if none matches.
155: */
156: public String getParameter(String name);
157:
158: /**
159: * Returns all values of a form parameter.
160: *
161: * <p>For example, calling <code>getParameterValues("a")</code>
162: * with the the query string <code>a=1&a=2</code> will
163: * return ["1", "2"].
164: *
165: * @param name the form parameter to return
166: * @return an array of matching form values or null if none matches.
167: */
168: public String[] getParameterValues(String name);
169:
170: /**
171: * Returns an enumeration of all form parameter names.
172: *
173: * <code><pre>
174: * Enumeration e = request.getParameterNames();
175: * while (e.hasMoreElements()) {
176: * String name = (String) e.nextElement();
177: * out.println(name + ": " + request.getParameter(name));
178: * }
179: * </pre></code>
180: */
181: public Enumeration getParameterNames();
182:
183: /**
184: * Returns a Map of the form parameters. The map is immutable.
185: * The keys are the form keys as returned by <code>getParameterNames</code>
186: * and the values are String arrays as returned by
187: * <code>getParameterValues</code>.
188: */
189: public Map getParameterMap();
190:
191: /**
192: * Returns an InputStream to retrieve POST data from the request.
193: * The stream will automatically end when the end of the POST data
194: * is complete.
195: */
196: public ServletInputStream getInputStream() throws IOException;
197:
198: /**
199: * Returns a reader to read POSTed data. Character encoding is
200: * based on the request data and is the same as
201: * <code>getCharacterEncoding()</code>
202: */
203: public BufferedReader getReader() throws IOException,
204: IllegalStateException;
205:
206: /**
207: * Returns the character encoding of the POSTed data.
208: */
209: public String getCharacterEncoding();
210:
211: /**
212: * Returns the content length of the data. This value may differ from
213: * the actual length of the data. Newer browsers
214: * supporting HTTP/1.1 may use "chunked" encoding which does
215: * not make the content length available.
216: *
217: * <p>The upshot is, rely on the input stream to end when the data
218: * completes.
219: */
220: public int getContentLength();
221:
222: /**
223: * Returns the request's mime-type.
224: */
225: public String getContentType();
226:
227: /**
228: * Returns the request's preferred locale, based on the Accept-Language
229: * header. If unspecified, returns the server's default locale.
230: */
231: public Locale getLocale();
232:
233: /**
234: * Returns an enumeration of all locales acceptable by the client.
235: */
236: public Enumeration getLocales();
237:
238: /**
239: * Returns true if the connection is secure, e.g. it uses SSL.
240: */
241: public boolean isSecure();
242:
243: /**
244: * Returns an attribute value.
245: *
246: * @param name the attribute name
247: * @return the attribute value
248: */
249: public Object getAttribute(String name);
250:
251: /**
252: * Sets an attribute value.
253: *
254: * @param name the attribute name
255: * @param o the attribute value
256: */
257: public void setAttribute(String name, Object o);
258:
259: /**
260: * Enumerates all attribute names in the request.
261: */
262: public Enumeration getAttributeNames();
263:
264: /**
265: * Removes the given attribute.
266: *
267: * @param name the attribute name
268: */
269: public void removeAttribute(String name);
270:
271: /**
272: * Returns a request dispatcher for later inclusion or forwarding. This
273: * is the servlet API equivalent to SSI includes. <code>uri</code>
274: * is relative to the request URI. Absolute URIs are relative to
275: * the application prefix (<code>getContextPath()</code>).
276: *
277: * <p>If <code>getRequestURI()</code> is /myapp/dir/test.jsp and the
278: * <code>uri</code> is "inc.jsp", the resulting page is
279: * /myapp/dir/inc.jsp.
280:
281: * <code><pre>
282: * RequestDispatcher disp;
283: * disp = getRequestDispatcher("inc.jsp?a=b");
284: * disp.include(request, response);
285: * </pre></code>
286: *
287: * @param uri path relative to <code>getRequestURI()</code>
288: * (including query string) for the included file.
289: * @return RequestDispatcher for later inclusion or forwarding.
290: */
291: public RequestDispatcher getRequestDispatcher(String uri);
292:
293: /**
294: * Returns the path of the URI.
295: */
296: public String getRealPath(String uri);
297: }
|