Home » tapestry-src-5.0.19 » org.apache.tapestry5.services » [javadoc | source]

    1   // Copyright 2006, 2007, 2008 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.tapestry5.services;
   16   
   17   import java.util.List;
   18   import java.util.Locale;
   19   
   20   /**
   21    * Generic version of {@link javax.servlet.http.HttpServletRequest}, used to encapsulate the Servlet API version, and to
   22    * help bridge the differences between Servlet API and Porlet API.
   23    * <p/>
   24    * <p/>
   25    * The Request service is a {@linkplain org.apache.tapestry5.ioc.services.PropertyShadowBuilder shadow} of the current
   26    * thread's request.
   27    */
   28   public interface Request
   29   {
   30       /**
   31        * Gets the {@link Session}. If create is false and the session has not be created previously, returns null.
   32        *
   33        * @param create true to force the creation of the session
   34        * @return the session (or null if create is false the session has not been previously created)
   35        */
   36       Session getSession(boolean create);
   37   
   38       /**
   39        * Returns the context path. This always starts with a "/" character and does not end with one, with the exception
   40        * of servlets in the root context, which return the empty string.
   41        */
   42       String getContextPath();
   43   
   44       /**
   45        * Returns a list of query parameter names, in alphabetical order.
   46        */
   47       List<String> getParameterNames();
   48   
   49       /**
   50        * Returns the query parameter value for the given name. Returns null if no such parameter is in the request. For a
   51        * multi-valued parameter, returns just the first value.
   52        */
   53       String getParameter(String name);
   54   
   55       /**
   56        * Returns the parameter values for the given name. Returns null if no such parameter is in the request.
   57        */
   58       String[] getParameters(String name);
   59   
   60       /**
   61        * Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the
   62        * query parameters. It doesn't include the context path.
   63        */
   64       String getPath();
   65   
   66       /**
   67        * Returns the locale of the client as determined from the request headers.
   68        */
   69       Locale getLocale();
   70   
   71       /**
   72        * Returns the names of all headers in the request.
   73        */
   74       List<String> getHeaderNames();
   75   
   76       /**
   77        * Returns the value of the specified request header as a <code>long</code> value that represents a
   78        * <code>Date</code> object. Use this method with headers that contain dates, such as
   79        * <code>If-Modified-Since</code>.
   80        * <p/>
   81        * The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case
   82        * insensitive.
   83        * <p/>
   84        * If the request did not have a header of the specified name, this method returns -1. If the header can't be
   85        * converted to a date, the method throws an <code>IllegalArgumentException</code>.
   86        *
   87        * @param name a <code>String</code> specifying the name of the header
   88        * @return a <code>long</code> value representing the date specified in the header expressed as the number of
   89        *         milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest
   90        * @throws IllegalArgumentException If the header value can't be converted to a date
   91        */
   92       long getDateHeader(String name);
   93   
   94       /**
   95        * Returns the named header as a string, or null if not found.
   96        */
   97       String getHeader(String name);
   98   
   99       /**
  100        * Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior). Ajax
  101        * action requests may behave quite differently than ordinary, page-based requests.  This implementation currently
  102        * depends on the client side setting a header: <strong>X-Requested-With=XMLHttpRequest</strong> (this is what
  103        * Prototype does).
  104        *
  105        * @return true if the request has an XmlHttpRequest origin
  106        */
  107       boolean isXHR();
  108   
  109       /**
  110        * Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
  111        *
  112        * @return a boolean indicating if the request was made using a secure channel
  113        */
  114       public boolean isSecure();
  115   
  116       /**
  117        * Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the
  118        * <code>Host</code> header, if any, or the resolved server name, or the server IP address.
  119        *
  120        * @return the name of the server
  121        */
  122       public String getServerName();
  123   
  124       /**
  125        * Checks whether the requested session ID is still valid.
  126        *
  127        * @return true if the request included a session id that is still active, false if the included session id has
  128        *         expired
  129        */
  130       boolean isRequestedSessionIdValid();
  131   
  132   
  133       /**
  134        * Returns the value of the named attribute as an <code>Object</code>, or <code>null</code> if no attribute of the
  135        * given name exists.  Because this method is a wrapper around {@link javax.servlet.ServletRequest#getAttribute(String)},
  136        * it is case <em>sensitive</em> (unlike most of Tapestry).
  137        *
  138        * @param name a <code>String</code> specifying the name of the attribute
  139        * @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does
  140        *         not exist
  141        */
  142       Object getAttribute(String name);
  143   
  144       /**
  145        * Stores an attribute in this request. Attributes are reset between requests (and remember that in Tapestry, there
  146        * is usually two requests per operation: the action request that redirects to a render request).
  147        *
  148        * @param name  a <code>String</code> specifying the name of the attribute
  149        * @param value the <code>Object</code> to be stored, or null to remove the attribute
  150        */
  151       void setAttribute(String name, Object value);
  152   
  153       /**
  154        * Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
  155        *
  156        * @return a string specifying the name of the method with which this request was made
  157        */
  158       public String getMethod();
  159   }

Home » tapestry-src-5.0.19 » org.apache.tapestry5.services » [javadoc | source]