001 // Copyright 2005 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.web;
016
017 import org.apache.tapestry.describe.Describable;
018
019 import javax.servlet.http.HttpServletRequest;
020 import java.security.Principal;
021 import java.util.List;
022 import java.util.Locale;
023
024 /**
025 * Contains information about the current request, including URLs, schemes, parameters, properties
026 * and attributes. This is essentially a generic version of
027 * {@link javax.servlet.http.HttpServletRequest}. In some cases, certain methods will be
028 * unsupported in some implementations (such as {@link #getHeader(String)} for Portlet Tapestry).
029 *
030 * @author Howard M. Lewis Ship
031 * @since 4.0
032 */
033 public interface WebRequest extends AttributeHolder, Describable
034 {
035 /**
036 * Returns the names of all query parameters for this request. Note that this may return an
037 * empty list if an HTML form submission uploads files (with a request encoding of
038 * multipart/form-data). Accessing query parameters in such an event requires parsing of the
039 * request input stream.
040 *
041 * @return List of Strings, in ascending alphabetical order
042 */
043
044 List getParameterNames();
045
046 /**
047 * Returns a parameter value. If the parameter was submitted with multiple values, then the
048 * first submitted value is returned. May return null if no parameter was submitted with the
049 * given name.
050 *
051 * @param parameterName
052 * name of parameter to obtain
053 * @return the corresponding value, or null if a value for the parameter was not submitted in
054 * the request
055 * @see #getParameterValues(String)
056 */
057
058 String getParameterValue(String parameterName);
059
060 /**
061 * Returns all parameter values for a particular parameter name. May return null.
062 * <p>
063 * The caller should <em>not modify</em> the returned value.
064 *
065 * @param parameterName
066 * name of parameter to obtain
067 * @return the corresponding values, or null if no values for the parameter were submitted in
068 * the request
069 * @see #getParameterValue(String)
070 */
071
072 String[] getParameterValues(String parameterName);
073
074 /**
075 * Returns the portion of the request URI that indicates the context of the request. The context
076 * path always comes first in a request URI. The path starts with a "/" character but does not
077 * end with a "/" character.
078 *
079 * @return The servlet context path.
080 */
081
082 String getContextPath();
083
084 /**
085 * Returns the current {@link WebSession}associated with this request, possibly creating it if
086 * it does not already exist. If create is false and the request has no valid session, this
087 * method returns null. To make sure the session is properly maintained, you must call this
088 * method <em>before</em> the response is committed.
089 *
090 * @param create
091 * if true, the session will be created and returned if it does not already exist
092 * @return The session, or null if it does not exist (and create is false)
093 */
094 WebSession getSession(boolean create);
095
096 /**
097 * Returns the name of the scheme used to make this request. For example, http, https, or ftp.
098 * Different schemes have different rules for constructing URLs, as noted in RFC 1738.
099 *
100 * @return The scheme.
101 */
102 String getScheme();
103
104 /**
105 * Returns the host name of the server that received the request. Note that behind a firewall,
106 * this may be obscured (i.e., it may be the name of the firewall server, which is not
107 * necessarily visible to clients outside the firewall).
108 *
109 * @return The name of the server.
110 * @see org.apache.tapestry.request.IRequestDecoder
111 */
112
113 String getServerName();
114
115 /**
116 * Returns the port number on which this request was received.
117 *
118 * @return The port number this request is acting on.
119 */
120
121 int getServerPort();
122
123 /**
124 * Returns the path portion of the request which triggered this request. Query parameters,
125 * scheme, server and port are omitted.
126 * <p>
127 * Note: portlets do not know their request URI.
128 * </p>
129 *
130 * @return The requested URI.
131 */
132
133 String getRequestURI();
134
135 /**
136 * Redirects to the indicated URL. If the URL is local, then a forward occurs. Otherwise, a
137 * client side redirect is returned to the client browser.
138 *
139 * @param URL
140 * The url to forward the request to.
141 */
142
143 void forward(String URL);
144
145 /**
146 * Returns the path of the resource which activated this request (this is the equivalent of the
147 * servlet path for a servlet request). The activation path will not end with a slash.
148 *
149 * @return The full servlet path (for servlet requests), or a blank string (for portlet requests).
150 */
151 String getActivationPath();
152
153 /**
154 * Return any additional path info beyond the servlet path itself. Path info, if non-null,
155 * begins with a path.
156 *
157 * @return path info, or null if no path info
158 */
159
160 String getPathInfo();
161
162 /**
163 * Returns the preferred locale to which content should be localized, as specified by the client
164 * or by the container. May return null.
165 *
166 * @return The locale associated with the request, may be null.
167 */
168 Locale getLocale();
169
170 /**
171 * Returns the value of the specified request header.
172 *
173 * @param name
174 * the name of the header to retrieve
175 * @return the header value as a string, or null if the header is not in the request.
176 */
177
178 String getHeader(String name);
179
180 /**
181 * Returns the value of the specified request header
182 * as a <code>long</code> value that represents a
183 * <code>Date</code> object. Use this method with
184 * headers that contain dates, such as
185 * <code>If-Modified-Since</code>.
186 *
187 * <p>The date is returned as
188 * the number of milliseconds since January 1, 1970 GMT.
189 * The header name is case insensitive.
190 *
191 * <p>If the request did not have a header of the
192 * specified name, this method returns -1. If the header
193 * can't be converted to a date, the method throws
194 * an <code>IllegalArgumentException</code>.
195 *
196 * @param name a <code>String</code> specifying the
197 * name of the header
198 *
199 * @return a <code>long</code> value representing the
200 * date specified in the header expressed as the number
201 * of milliseconds since January 1, 1970 GMT, or -1 if
202 * the named header was not included with the reqest
203 *
204 * @exception IllegalArgumentException If the header value
205 * can't be converted to a date
206 */
207 long getDateHeader(String name);
208
209 /**
210 * Returns the value of the specified request header
211 * as an <code>int</code>. If the request does not have a header
212 * of the specified name, this method returns -1. If the
213 * header cannot be converted to an integer, this method
214 * throws a <code>NumberFormatException</code>.
215 *
216 * <p>The header name is case insensitive.
217 *
218 * @param name a <code>String</code> specifying the name
219 * of a request header
220 *
221 * @return an integer expressing the value of the request header or -1
222 * if the request doesn't have a header of this name
223 *
224 * @exception NumberFormatException If the header value can't be
225 * converted to an <code>int</code>
226 */
227 int getIntHeader(String name);
228
229 /**
230 * Returns the login of the user making this request, if the user has been authenticated, or
231 * null if the user has not been authenticated.
232 *
233 * @return a String specifying the login of the user making this request, or null if the user
234 * login is not known.
235 */
236
237 String getRemoteUser();
238
239 /**
240 * Returns a java.security.Principal object containing the name of the current authenticated
241 * user.
242 *
243 * @return a java.security.Principal containing the name of the user making this request, or
244 * null if the user has not been authenticated.
245 */
246 Principal getUserPrincipal();
247
248 /**
249 * * Returns a boolean indicating whether the authenticated user is included in the specified
250 * logical "role". Roles and role membership can be defined using deployment descriptors. If the
251 * user has not been authenticated, the method returns false.
252 *
253 * @param role
254 * a String specifying the name of the role
255 * @return a boolean indicating whether the user making this request belongs to a given role;
256 * false if the user has not been authenticated.
257 */
258 boolean isUserInRole(String role);
259
260 /**
261 * Taken from {@link HttpServletRequest}. Indicates if this request is coming in on
262 * a SSL/secure connection.
263 *
264 * @return True if secure, false otherwise.
265 */
266 boolean isSecure();
267 }