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 java.security.Principal;
018 import java.util.List;
019 import java.util.Locale;
020
021 import org.apache.tapestry.describe.Describable;
022
023 /**
024 * Contains information about the current request, including URLs, schemes, parameters, properties
025 * and attributes. This is essentially a generic version of
026 * {@link javax.servlet.http.HttpServletRequest}. In some cases, certain methods will be
027 * unsupported in some implementations (such as {@link #getHeader(String)} for Portlet Tapestry).
028 *
029 * @author Howard M. Lewis Ship
030 * @since 4.0
031 */
032 public interface WebRequest extends AttributeHolder, Describable
033 {
034 /**
035 * Returns the names of all query parameters for this request. Note that this may return an
036 * empty list if an HTML form submission uploads files (with a request encoding of
037 * multipart/form-data). Accessing query parameters in such an event requires parsing of the
038 * request input stream.
039 *
040 * @returns List of Strings, in ascending alphabetical order
041 */
042
043 public List getParameterNames();
044
045 /**
046 * Returns a parameter value. If the parameter was submitted with multiple values, then the
047 * first submitted value is returned. May return null if no parameter was submitted with the
048 * given name.
049 *
050 * @param parameterName
051 * name of parameter to obtain
052 * @return the corresponding value, or null if a value for the parameter was not submitted in
053 * the request
054 * @see #getParameterValues(String)
055 */
056
057 public String getParameterValue(String parameterName);
058
059 /**
060 * Returns all parameter values for a particular parameter name. May return null.
061 * <p>
062 * The caller should <em>not modify</em> the returned value.
063 *
064 * @param parameterName
065 * name of parameter to obtain
066 * @return the corresponding values, or null if no values for the parameter were submitted in
067 * the request
068 * @see #getParameterValue(String)
069 */
070
071 public String[] getParameterValues(String parameterName);
072
073 /**
074 * Returns the portion of the request URI that indicates the context of the request. The context
075 * path always comes first in a request URI. The path starts with a "/" character but does not
076 * end with a "/" character.
077 */
078
079 public String getContextPath();
080
081 /**
082 * Returns the current {@link WebSession}associated with this request, possibly creating it if
083 * it does not already exist. If create is false and the request has no valid session, this
084 * method returns null. To make sure the session is properly maintained, you must call this
085 * method <em>before</em> the response is committed.
086 *
087 * @param create
088 * if true, the session will be created and returned if it does not already exist
089 * @returns The session, or null if it does not exist (and create is false)
090 */
091 public WebSession getSession(boolean create);
092
093 /**
094 * Returns the name of the scheme used to make this request. For example, http, https, or ftp.
095 * Different schemes have different rules for constructing URLs, as noted in RFC 1738.
096 */
097 public String getScheme();
098
099 /**
100 * Returns the host name of the server that received the request. Note that behind a firewall,
101 * this may be obscured (i.e., it may be the name of the firewall server, which is not
102 * necessarily visible to clients outside the firewall).
103 *
104 * @see org.apache.tapestry.request.IRequestDecoder
105 */
106
107 public String getServerName();
108
109 /**
110 * Returns the port number on which this request was received.
111 */
112
113 public int getServerPort();
114
115 /**
116 * Returns the path portion of the request which triggered this request. Query parameters,
117 * scheme, server and port are omitted.
118 * <p>
119 * Note: portlets do not know their request URI.
120 */
121
122 public String getRequestURI();
123
124 /**
125 * Redirects to the indicated URL. If the URL is local, then a forward occurs. Otherwise, a
126 * client side redirect is returned to the client browser.
127 */
128
129 public void forward(String URL);
130
131 /**
132 * Returns the path of the resource which activated this request (this is the equivalent of the
133 * servlet path for a servlet request). The activation path will not end with a slash.
134 *
135 * @returns the full servlet path (for servlet requests), or a blank string (for portlet
136 * requests).
137 */
138 public String getActivationPath();
139
140 /**
141 * Return any additional path info beyond the servlet path itself. Path info, if non-null,
142 * begins with a path.
143 *
144 * @return path info, or null if no path info
145 */
146
147 public String getPathInfo();
148
149 /**
150 * Returns the preferred locale to which content should be localized, as specified by the client
151 * or by the container. May return null.
152 */
153 public Locale getLocale();
154
155 /**
156 * Returns the value of the specified request header.
157 *
158 * @param name
159 * the name of the header to retrieve
160 * @return the header value as a string, or null if the header is not in the request.
161 */
162
163 public String getHeader(String name);
164
165 /**
166 * Returns the login of the user making this request, if the user has been authenticated, or
167 * null if the user has not been authenticated.
168 *
169 * @return a String specifying the login of the user making this request, or null if the user
170 * login is not known.
171 */
172
173 public String getRemoteUser();
174
175 /**
176 * Returns a java.security.Principal object containing the name of the current authenticated
177 * user.
178 *
179 * @return a java.security.Principal containing the name of the user making this request, or
180 * null if the user has not been authenticated.
181 */
182 public Principal getUserPrincipal();
183
184 /**
185 * * Returns a boolean indicating whether the authenticated user is included in the specified
186 * logical "role". Roles and role membership can be defined using deployment descriptors. If the
187 * user has not been authenticated, the method returns false.
188 *
189 * @param role
190 * a String specifying the name of the role
191 * @return a boolean indicating whether the user making this request belongs to a given role;
192 * false if the user has not been authenticated.
193 */
194 public boolean isUserInRole(String role);
195 }