001 // Copyright 2006, 2007, 2008 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry.services;
016
017 import java.util.List;
018 import java.util.Locale;
019
020 /**
021 * Generic version of {@link javax.servlet.http.HttpServletRequest}, used to encapsulate the Servlet API version, and to
022 * help bridge the differences between Servlet API and Porlet API.
023 */
024 public interface Request
025 {
026 /**
027 * Gets the {@link Session}. If create is false and the session has not be created previously, returns null.
028 *
029 * @param create true to force the creation of the session
030 * @return the session (or null if create is false the session has not been previously created)
031 */
032 Session getSession(boolean create);
033
034 /**
035 * Returns the context path. This always starts with a "/" character and does not end with one, with the exception
036 * of servlets in the root context, which return the empty string.
037 */
038 String getContextPath();
039
040 /**
041 * Returns a list of query parameter names, in alphabetical order.
042 */
043 List<String> getParameterNames();
044
045 /**
046 * Returns the query parameter value for the given name. Returns null if no such parameter is in the request. For a
047 * multi-valued parameter, returns just the first value.
048 */
049 String getParameter(String name);
050
051 /**
052 * Returns the parameter values for the given name. Returns null if no such parameter is in the request.
053 */
054 String[] getParameters(String name);
055
056 /**
057 * Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the
058 * query parameters. It doesn't include the context path.
059 */
060 String getPath();
061
062 /**
063 * Returns the locale of the client as determined from the request headers.
064 */
065 Locale getLocale();
066
067 /**
068 * Returns the names of all headers in the request.
069 */
070 List<String> getHeaderNames();
071
072 /**
073 * Returns the value of the specified request header as a <code>long</code> value that represents a
074 * <code>Date</code> object. Use this method with headers that contain dates, such as
075 * <code>If-Modified-Since</code>.
076 * <p/>
077 * The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case
078 * insensitive.
079 * <p/>
080 * If the request did not have a header of the specified name, this method returns -1. If the header can't be
081 * converted to a date, the method throws an <code>IllegalArgumentException</code>.
082 *
083 * @param name a <code>String</code> specifying the name of the header
084 * @return a <code>long</code> value representing the date specified in the header expressed as the number of
085 * milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest
086 * @throws IllegalArgumentException If the header value can't be converted to a date
087 */
088 long getDateHeader(String name);
089
090 /**
091 * Returns the named header as a string, or null if not found.
092 */
093 String getHeader(String name);
094
095 /**
096 * Sets the encoding of the request, which must occur before any parameters for the request are read.
097 *
098 * @param requestEncoding charset used when parsing parameters
099 */
100 void setEncoding(String requestEncoding);
101
102 /**
103 * Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior). Ajax
104 * action requests may behave quite differently than ordinary, page-based requests. This implementation currently
105 * depends on the client side setting a header: <strong>X-Requested-With=XMLHttpRequest</strong> (this is what
106 * Prototype does).
107 *
108 * @return true if the request has an XmlHttpRequest origin
109 */
110 boolean isXHR();
111
112 /**
113 * Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
114 *
115 * @return a boolean indicating if the request was made using a secure channel
116 */
117 public boolean isSecure();
118
119 /**
120 * Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the
121 * <code>Host</code> header, if any, or the resolved server name, or the server IP address.
122 *
123 * @return the name of the server
124 */
125 public String getServerName();
126
127 /**
128 * Checks whether the requested session ID is still valid.
129 *
130 * @return true if the request included a session id that is still active, false if the included session id has
131 * expired
132 */
133 boolean isRequestedSessionIdValid();
134
135
136 /**
137 * Returns the value of the named attribute as an <code>Object</code>, or <code>null</code> if no attribute of the
138 * given name exists. Because this method is a wrapper around {@link javax.servlet.ServletRequest#getAttribute(String)},
139 * it is case <em>sensitive</em> (unlike most of Tapestry).
140 *
141 * @param name a <code>String</code> specifying the name of the attribute
142 * @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does
143 * not exist
144 */
145 Object getAttribute(String name);
146
147 /**
148 * Stores an attribute in this request. Attributes are reset between requests (and remember that in Tapestry, there
149 * is usually two requests per operation: the action request that redirects to a render request).
150 *
151 * @param name a <code>String</code> specifying the name of the attribute
152 * @param value the <code>Object</code> to be stored, or null to remove the attribute
153 */
154 void setAttribute(String name, Object value);
155 }