Clover coverage report - Code Coverage for tapestry release 4.0-beta-10
Coverage timestamp: Sat Oct 8 2005 19:08:05 EDT
file stats: LOC: 186   Methods: 0
NCLOC: 23   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
WebRequest.java - - - -
coverage
 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 java.security.Principal;
 18    import java.util.List;
 19    import java.util.Locale;
 20   
 21    import org.apache.tapestry.describe.Describable;
 22   
 23    /**
 24    * Contains information about the current request, including URLs, schemes, parameters, properties
 25    * and attributes. This is essentially a generic version of
 26    * {@link javax.servlet.http.HttpServletRequest}. In some cases, certain methods will be
 27    * unsupported in some implementations (such as {@link #getHeader(String)} for Portlet Tapestry).
 28    *
 29    * @author Howard M. Lewis Ship
 30    * @since 4.0
 31    */
 32    public interface WebRequest extends AttributeHolder, Describable
 33    {
 34    /**
 35    * Returns the names of all query parameters for this request. Note that this may return an
 36    * empty list if an HTML form submission uploads files (with a request encoding of
 37    * multipart/form-data). Accessing query parameters in such an event requires parsing of the
 38    * request input stream.
 39    *
 40    * @returns List of Strings, in ascending alphabetical order
 41    */
 42   
 43    public List getParameterNames();
 44   
 45    /**
 46    * Returns a parameter value. If the parameter was submitted with multiple values, then the
 47    * first submitted value is returned. May return null if no parameter was submitted with the
 48    * given name.
 49    *
 50    * @param parameterName
 51    * name of parameter to obtain
 52    * @return the corresponding value, or null if a value for the parameter was not submitted in
 53    * the request
 54    * @see #getParameterValues(String)
 55    */
 56   
 57    public String getParameterValue(String parameterName);
 58   
 59    /**
 60    * Returns all parameter values for a particular parameter name. May return null.
 61    * <p>
 62    * The caller should <em>not modify</em> the returned value.
 63    *
 64    * @param parameterName
 65    * name of parameter to obtain
 66    * @return the corresponding values, or null if no values for the parameter were submitted in
 67    * the request
 68    * @see #getParameterValue(String)
 69    */
 70   
 71    public String[] getParameterValues(String parameterName);
 72   
 73    /**
 74    * Returns the portion of the request URI that indicates the context of the request. The context
 75    * path always comes first in a request URI. The path starts with a "/" character but does not
 76    * end with a "/" character.
 77    */
 78   
 79    public String getContextPath();
 80   
 81    /**
 82    * Returns the current {@link WebSession}associated with this request, possibly creating it if
 83    * it does not already exist. If create is false and the request has no valid session, this
 84    * method returns null. To make sure the session is properly maintained, you must call this
 85    * method <em>before</em> the response is committed.
 86    *
 87    * @param create
 88    * if true, the session will be created and returned if it does not already exist
 89    * @returns The session, or null if it does not exist (and create is false)
 90    */
 91    public WebSession getSession(boolean create);
 92   
 93    /**
 94    * Returns the name of the scheme used to make this request. For example, http, https, or ftp.
 95    * Different schemes have different rules for constructing URLs, as noted in RFC 1738.
 96    */
 97    public String getScheme();
 98   
 99    /**
 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 servlet path, plus
 133    * path info, for a servlet request).
 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    * Returns the preferred locale to which content should be localized, as specified by the client
 142    * or by the container. May return null.
 143    */
 144    public Locale getLocale();
 145   
 146    /**
 147    * Returns the value of the specified request header.
 148    *
 149    * @param name
 150    * the name of the header to retrieve
 151    * @return the header value as a string, or null if the header is not in the request.
 152    */
 153   
 154    public String getHeader(String name);
 155   
 156    /**
 157    * Returns the login of the user making this request, if the user has been authenticated, or
 158    * null if the user has not been authenticated.
 159    *
 160    * @return a String specifying the login of the user making this request, or null if the user
 161    * login is not known.
 162    */
 163   
 164    public String getRemoteUser();
 165   
 166    /**
 167    * Returns a java.security.Principal object containing the name of the current authenticated
 168    * user.
 169    *
 170    * @return a java.security.Principal containing the name of the user making this request, or
 171    * null if the user has not been authenticated.
 172    */
 173    public Principal getUserPrincipal();
 174   
 175    /**
 176    * * Returns a boolean indicating whether the authenticated user is included in the specified
 177    * logical "role". Roles and role membership can be defined using deployment descriptors. If the
 178    * user has not been authenticated, the method returns false.
 179    *
 180    * @param role
 181    * a String specifying the name of the role
 182    * @return a boolean indicating whether the user making this request belongs to a given role;
 183    * false if the user has not been authenticated.
 184    */
 185    public boolean isUserInRole(String role);
 186    }