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 | } |