Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||||
WebRequest |
|
| 1.0;1 |
1 | // Copyright 2005 The Apache Software Foundation |
|
2 | // |
|
3 | // Licensed under the Apache License, Version 2.0 (the "License"); |
|
4 | // you may not use this file except in compliance with the License. |
|
5 | // You may obtain a copy of the License at |
|
6 | // |
|
7 | // http://www.apache.org/licenses/LICENSE-2.0 |
|
8 | // |
|
9 | // Unless required by applicable law or agreed to in writing, software |
|
10 | // distributed under the License is distributed on an "AS IS" BASIS, |
|
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
12 | // See the License for the specific language governing permissions and |
|
13 | // limitations under the License. |
|
14 | ||
15 | package org.apache.tapestry.web; |
|
16 | ||
17 | import org.apache.tapestry.describe.Describable; |
|
18 | ||
19 | import javax.servlet.http.HttpServletRequest; |
|
20 | import java.security.Principal; |
|
21 | import java.util.List; |
|
22 | import java.util.Locale; |
|
23 | ||
24 | /** |
|
25 | * Contains information about the current request, including URLs, schemes, parameters, properties |
|
26 | * and attributes. This is essentially a generic version of |
|
27 | * {@link javax.servlet.http.HttpServletRequest}. In some cases, certain methods will be |
|
28 | * unsupported in some implementations (such as {@link #getHeader(String)} for Portlet Tapestry). |
|
29 | * |
|
30 | * @author Howard M. Lewis Ship |
|
31 | * @since 4.0 |
|
32 | */ |
|
33 | public interface WebRequest extends AttributeHolder, Describable |
|
34 | { |
|
35 | /** |
|
36 | * Returns the names of all query parameters for this request. Note that this may return an |
|
37 | * empty list if an HTML form submission uploads files (with a request encoding of |
|
38 | * multipart/form-data). Accessing query parameters in such an event requires parsing of the |
|
39 | * request input stream. |
|
40 | * |
|
41 | * @return List of Strings, in ascending alphabetical order |
|
42 | */ |
|
43 | ||
44 | List getParameterNames(); |
|
45 | ||
46 | /** |
|
47 | * Returns a parameter value. If the parameter was submitted with multiple values, then the |
|
48 | * first submitted value is returned. May return null if no parameter was submitted with the |
|
49 | * given name. |
|
50 | * |
|
51 | * @param parameterName |
|
52 | * name of parameter to obtain |
|
53 | * @return the corresponding value, or null if a value for the parameter was not submitted in |
|
54 | * the request |
|
55 | * @see #getParameterValues(String) |
|
56 | */ |
|
57 | ||
58 | String getParameterValue(String parameterName); |
|
59 | ||
60 | /** |
|
61 | * Returns all parameter values for a particular parameter name. May return null. |
|
62 | * <p> |
|
63 | * The caller should <em>not modify</em> the returned value. |
|
64 | * |
|
65 | * @param parameterName |
|
66 | * name of parameter to obtain |
|
67 | * @return the corresponding values, or null if no values for the parameter were submitted in |
|
68 | * the request |
|
69 | * @see #getParameterValue(String) |
|
70 | */ |
|
71 | ||
72 | String[] getParameterValues(String parameterName); |
|
73 | ||
74 | /** |
|
75 | * Returns the portion of the request URI that indicates the context of the request. The context |
|
76 | * path always comes first in a request URI. The path starts with a "/" character but does not |
|
77 | * end with a "/" character. |
|
78 | * |
|
79 | * @return The servlet context path. |
|
80 | */ |
|
81 | ||
82 | String getContextPath(); |
|
83 | ||
84 | /** |
|
85 | * Returns the current {@link WebSession}associated with this request, possibly creating it if |
|
86 | * it does not already exist. If create is false and the request has no valid session, this |
|
87 | * method returns null. To make sure the session is properly maintained, you must call this |
|
88 | * method <em>before</em> the response is committed. |
|
89 | * |
|
90 | * @param create |
|
91 | * if true, the session will be created and returned if it does not already exist |
|
92 | * @return The session, or null if it does not exist (and create is false) |
|
93 | */ |
|
94 | WebSession getSession(boolean create); |
|
95 | ||
96 | /** |
|
97 | * Returns the name of the scheme used to make this request. For example, http, https, or ftp. |
|
98 | * Different schemes have different rules for constructing URLs, as noted in RFC 1738. |
|
99 | * |
|
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 | } |