Coverage Report - org.apache.tapestry.web.WebRequest
 
Classes in this File Line Coverage Branch Coverage Complexity
WebRequest
N/A
N/A
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  
 }