001: /*
002: * Copyright (c) JForum Team
003: * All rights reserved.
004: *
005: * Redistribution and use in source and binary forms,
006: * with or without modification, are permitted provided
007: * that the following conditions are met:
008: *
009: * 1) Redistributions of source code must retain the above
010: * copyright notice, this list of conditions and the
011: * following disclaimer.
012: * 2) Redistributions in binary form must reproduce the
013: * above copyright notice, this list of conditions and
014: * the following disclaimer in the documentation and/or
015: * other materials provided with the distribution.
016: * 3) Neither the name of "Rafael Steil" nor
017: * the names of its contributors may be used to endorse
018: * or promote products derived from this software without
019: * specific prior written permission.
020: *
021: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT
022: * HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
023: * EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
024: * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
025: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR
026: * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
027: * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
028: * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
029: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES
030: * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
031: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
032: * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
033: * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
034: * IN CONTRACT, STRICT LIABILITY, OR TORT
035: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
036: * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
037: * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
038: *
039: *
040: * The JForum Project
041: * http://www.jforum.net
042: */
043: package net.jforum.context;
044:
045: import java.io.UnsupportedEncodingException;
046: import java.util.Enumeration;
047: import java.util.Locale;
048:
049: import javax.servlet.http.Cookie;
050:
051: /**
052: * User: SergeMaslyukov Date: 20.08.2006 Time: 17:18:03 <p/> $Id: WebContextRequest.java,v 1.1
053: * 2006/08/20 15:30:29 sergemaslyukov Exp $
054: */
055: public interface RequestContext {
056: /**
057: * Returns the part of this request's URL from the protocol name up to the query string in the
058: * first line of the HTTP request. The web container does not decode this String. For example:
059: *
060: * <table summary="Examples of Returned Values">
061: * <tr align=left>
062: * <th>First line of HTTP request </th>
063: * <th> Returned Value</th>
064: * <tr>
065: * <td>POST /some/path.html HTTP/1.1
066: * <td>
067: * <td>/some/path.html
068: * <tr>
069: * <td>GET http://foo.bar/a.html HTTP/1.0
070: * <td>
071: * <td>/a.html
072: * <tr>
073: * <td>HEAD /xyz?a=b HTTP/1.1
074: * <td>
075: * <td>/xyz </table>
076: *
077: * <p>
078: * To reconstruct an URL with a scheme and host, use
079: * {@link javax.servlet.http.HttpUtils#getRequestURL}.
080: *
081: * @return a <code>String</code> containing the part of the URL from the protocol name up to
082: * the query string
083: *
084: * @see javax.servlet.http.HttpUtils#getRequestURL
085: */
086: public String getRequestURI();
087:
088: /**
089: * Returns the query string that is contained in the request URL after the path. This method
090: * returns <code>null</code> if the URL does not have a query string. Same as the value of the
091: * CGI variable QUERY_STRING.
092: *
093: * @return a <code>String</code> containing the query string or <code>null</code> if the URL
094: * contains no query string. The value is not decoded by the container.
095: */
096: public String getQueryString();
097:
098: /**
099: * Returns the value of the specified request header as a <code>String</code>. If the request
100: * did not include a header of the specified name, this method returns <code>null</code>. If
101: * there are multiple headers with the same name, this method returns the first head in the
102: * request. The header name is case insensitive. You can use this method with any request
103: * header.
104: *
105: * @param name
106: * a <code>String</code> specifying the header name
107: *
108: * @return a <code>String</code> containing the value of the requested header, or
109: * <code>null</code> if the request does not have a header of that name
110: */
111: public String getHeader(String name);
112:
113: /**
114: * Returns an array containing all of the <code>Cookie</code> objects the client sent with
115: * this request. This method returns <code>null</code> if no cookies were sent.
116: *
117: * @return an array of all the <code>Cookies</code> included with this request, or
118: * <code>null</code> if the request has no cookies
119: */
120: public Cookie[] getCookies();
121:
122: /**
123: * Returns the Internet Protocol (IP) address of the client or last proxy that sent the request.
124: * For HTTP servlets, same as the value of the CGI variable <code>REMOTE_ADDR</code>.
125: *
126: * @return a <code>String</code> containing the IP address of the client that sent the request
127: */
128: public String getRemoteAddr();
129:
130: /**
131: * Returns the port number to which the request was sent. It is the value of the part after ":"
132: * in the <code>Host</code> header value, if any, or the server port where the client
133: * connection was accepted on.
134: *
135: * @return an integer specifying the port number
136: */
137: public int getServerPort();
138:
139: /**
140: * Returns the name of the scheme used to make this request, for example, <code>http</code>,
141: * <code>https</code>, or <code>ftp</code>. Different schemes have different rules for
142: * constructing URLs, as noted in RFC 1738.
143: *
144: * @return a <code>String</code> containing the name of the scheme used to make this request
145: */
146: public String getScheme();
147:
148: /**
149: * Returns the host name of the server to which the request was sent. It is the value of the
150: * part before ":" in the <code>Host</code> header value, if any, or the resolved server name,
151: * or the server IP address.
152: *
153: * @return a <code>String</code> containing the name of the server
154: */
155: public String getServerName();
156:
157: /**
158: * Removes an attribute from this request. This method is not generally needed as attributes
159: * only persist as long as the request is being handled.
160: *
161: * <p>
162: * Attribute names should follow the same conventions as package names. Names beginning with
163: * <code>java.*</code>, <code>javax.*</code>, and <code>com.sun.*</code>, are reserved
164: * for use by Sun Microsystems.
165: *
166: * @param name a <code>String</code> specifying the name of the attribute to remove
167: */
168: public void removeAttribute(String name);
169:
170: /**
171: * Stores an attribute in this request. Attributes are reset between requests. This method is
172: * most often used in conjunction with {@link javax.servlet.RequestDispatcher}.
173: *
174: * <p>
175: * Attribute names should follow the same conventions as package names. Names beginning with
176: * <code>java.*</code>, <code>javax.*</code>, and <code>com.sun.*</code>, are reserved
177: * for use by Sun Microsystems. <br>
178: * If the object passed in is null, the effect is the same as calling {@link #removeAttribute}.
179: * <br>
180: * It is warned that when the request is dispatched from the servlet resides in a different web
181: * application by <code>RequestDispatcher</code>, the object set by this method may not be
182: * correctly retrieved in the caller servlet.
183: *
184: * @param name a <code>String</code> specifying the name of the attribute
185: * @param o the <code>Object</code> to be stored
186: */
187: public void setAttribute(String name, Object o);
188:
189: /**
190: * Returns the value of the named attribute as an <code>Object</code>, or <code>null</code>
191: * if no attribute of the given name exists.
192: *
193: * <p>
194: * Attributes can be set two ways. The servlet container may set attributes to make available
195: * custom information about a request. For example, for requests made using HTTPS, the attribute
196: * <code>javax.servlet.request.X509Certificate</code> can be used to retrieve information on
197: * the certificate of the client. Attributes can also be set programatically using
198: * {@link #setAttribute}. This allows information to be embedded into a request before a
199: * {@link javax.servlet.RequestDispatcher} call.
200: *
201: * <p>
202: * Attribute names should follow the same conventions as package names. This specification
203: * reserves names matching <code>java.*</code>, <code>javax.*</code>, and
204: * <code>sun.*</code>.
205: *
206: * @param name a <code>String</code> specifying the name of the attribute
207: * @return an <code>Object</code> containing the value of the attribute,
208: * or <code>null</code> if the attribute does not exist
209: */
210:
211: public Object getAttribute(String name);
212:
213: /**
214: * Overrides the name of the character encoding used in the body of this request. This method
215: * must be called prior to reading request parameters or reading input using getReader().
216: *
217: * @param env a <code>String</code> containing the name of the character encoding.
218: * @throws java.io.UnsupportedEncodingException if this is not a valid encoding
219: */
220:
221: public void setCharacterEncoding(String env)
222: throws UnsupportedEncodingException;
223:
224: /**
225: * Returns the current <code>HttpSession</code> associated with this request or, if there is
226: * no current session and <code>create</code> is true, returns a new session.
227: *
228: * <p>
229: * If <code>create</code> is <code>false</code> and the request has no valid
230: * <code>HttpSession</code>, this method returns <code>null</code>.
231: *
232: * <p>
233: * To make sure the session is properly maintained, you must call this method before the
234: * response is committed. If the container is using cookies to maintain session integrity and is
235: * asked to create a new session when the response is committed, an IllegalStateException is
236: * thrown.
237: *
238: * @param create <code>true</code> to create a new session for this request if necessary;
239: * <code>false</code> to return <code>null</code> if there's no current session
240: * @return the <code>HttpSession</code> associated with this request or <code>null</code> if
241: * <code>create</code> is <code>false</code> and the request has no valid session
242: *
243: * @see #getSessionContext()
244: */
245:
246: public SessionContext getSessionContext(boolean create);
247:
248: /**
249: * Returns the current session associated with this request, or if the request does not have a
250: * session, creates one.
251: *
252: * @return the <code>HttpSession</code> associated with this request
253: * @see #getSessionContext(boolean)
254: */
255:
256: public SessionContext getSessionContext();
257:
258: /**
259: * Returns the portion of the request URI that indicates the context of the request. The context
260: * path always comes first in a request URI. The path starts with a "/" character but does not
261: * end with a "/" character. For servlets in the default (root) context, this method returns "".
262: * The container does not decode this string.
263: *
264: * @return a <code>String</code> specifying the portion of the request URI that indicates the
265: * context of the request
266: */
267:
268: public String getContextPath();
269:
270: /**
271: * Returns the login of the user making this request, if the user has been authenticated, or
272: * <code>null</code> if the user has not been authenticated. Whether the user name is sent
273: * with each subsequent request depends on the browser and type of authentication. Same as the
274: * value of the CGI variable REMOTE_USER.
275: *
276: * @return a <code>String</code> specifying the login of the user making this request, or
277: * <code>null</code> if the user login is not known
278: */
279:
280: public String getRemoteUser();
281:
282: /**
283: * Gets an parameter that is a number. A call to <code>Integer#parseInt(String)</code> is made
284: * to do the conversion
285: *
286: * @param parameter The parameter name to get the value
287: * @return int
288: */
289: public int getIntParameter(String parameter);
290:
291: /**
292: * Returns an array of <code>String</code> objects containing all of the values the given
293: * request parameter has, or <code>null</code> if the parameter does not exist.
294: *
295: * <p>
296: * If the parameter has a single value, the array has a length of 1.
297: *
298: * @param name a <code>String</code> containing the name of the parameter
299: * whose value is requested
300: *
301: * @return an array of <code>String</code> objects containing the parameter's values
302: * @see #getParameter
303: */
304: public String[] getParameterValues(String name);
305:
306: /**
307: * Returns the value of a request parameter as a <code>String</code>, or <code>null</code>
308: * if the parameter does not exist. Request parameters are extra information sent with the
309: * request. For HTTP servlets, parameters are contained in the query string or posted form data.
310: *
311: * <p>
312: * You should only use this method when you are sure the parameter has only one value. If the
313: * parameter might have more than one value, use {@link #getParameterValues}.
314: *
315: * <p>
316: * If you use this method with a multivalued parameter, the value returned is equal to the first
317: * value in the array returned by <code>getParameterValues</code>.
318: *
319: * <p>
320: * If the parameter data was sent in the request body, such as occurs with an HTTP POST request,
321: * then reading the body directly via {@link #getInputStream} or {@link #getReader} can
322: * interfere with the execution of this method.
323: *
324: * @param name a <code>String</code> specifying the name of the parameter
325: * @return a <code>String</code> representing the single value of the parameter
326: * @see #getParameterValues
327: */
328: public String getParameter(String name);
329:
330: /**
331: * Returns an <code>Enumeration</code> of <code>String</code> objects containing the names
332: * of the parameters contained in this request. If the request has no parameters, the method
333: * returns an empty <code>Enumeration</code>.
334: *
335: * @return an <code>Enumeration</code> of <code>String</code> objects, each
336: * <code>String</code> containing the name of a request parameter; or an empty
337: * <code>Enumeration</code> if the request has no parameters
338: */
339: public Enumeration getParameterNames();
340:
341: /**
342: * Gets the <i>action</i> of the current request.
343: *
344: * An <i>Action</i> is the parameter name which specifies what next action should be done by
345: * the system. It may be add or edit a post, editing the groups, whatever. In the URL, the
346: * Action can the represented in two forms:
347: * <p>
348: * <blockquote> <code>
349: * http://www.host.com/webapp/servletName?module=groups&action=list
350: * </code>
351: * </blockquote>
352: * <p>
353: * or
354: * <p>
355: * <blockquote> <code>
356: * http://www.host.com/webapp/servletName/groups/list
357: * </code> </blockquote>
358: * <p>
359: * In both situations, the action's name is "list".
360: *
361: * @return String representing the action name
362: */
363: public String getAction();
364:
365: /**
366: * Gets the <i>module</i> of the current request.
367: *
368: * A <i>Module</i> is the parameter name which specifies what module the user is requesting. It
369: * may be the group administration, the topics or anything else configured module. In the URL,
370: * the Module can the represented in two forms:
371: * <p>
372: * <blockquote> <code>
373: * http://www.host.com/webapp/servletName?module=groups&action=list
374: * </code>
375: * </blockquote>
376: * <p>
377: * or
378: * <p>
379: * <blockquote> <code>
380: * http://www.host.com/webapp/servletName/groups/list
381: * </code> </blockquote>
382: * <p>
383: * In both situations, the module's name is "groups".
384: *
385: * @return String representing the module name
386: */
387: public String getModule();
388:
389: /**
390: * Adds a new parameter to the request.
391: * If there is already one parameter which name is equals to the
392: * value of the "name" parameter, a set of values associated to that
393: * name will be generated, thus requiring a call to getParameterValues()
394: * to retrieve them all.
395: *
396: * If you want to <strong>replace</strong> a possible existing value,
397: * use {@link #addOrReplaceParameter(String, Object)}
398: *
399: * @param name Parameter name
400: * @param value Parameter value
401: */
402: public void addParameter(String name, Object value);
403:
404: /**
405: * Replace or add a parameter. If it does not exist, it is added to the list,
406: * otherwise the existing value will be replaced by the new value.
407: *
408: * @param name
409: * @param value
410: */
411: public void addOrReplaceParameter(String name, Object value);
412:
413: /**
414: * Gets some request parameter as <code>Object</code>. This method may be used when you have
415: * to get some value of a <i>multipart/form-data</i> request, like a image of file. <br>
416: *
417: * @param parameter String
418: * @return Object
419: */
420: public Object getObjectParameter(String parameter);
421:
422: /**
423: * Gets user browser's locale. This method may be used during first installation to
424: * automatically switch to corresponding language I18N resource.
425: *
426: * @return Locale
427: */
428: public Locale getLocale();
429: }
|