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}