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    }