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
015package org.apache.tapestry.web;
016
017import java.security.Principal;
018import java.util.List;
019import java.util.Locale;
020
021import 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 */
032public 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}