    001// Copyright 2006, 2007, 2008, 2011, 2012 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.tapestry5.services;
    016
    017import java.util.List;
    018import java.util.Locale;
    019
    020/**
    021 * Generic version of {@link javax.servlet.http.HttpServletRequest}, used to encapsulate the Servlet API version, and to
    022 * help bridge the differences between Servlet API and Porlet API.
    023 * <p/>
    024 * The Request service is a {@linkplain org.apache.tapestry5.ioc.services.PropertyShadowBuilder shadow} of the current
    025 * thread's request.
    026 */
    027public interface Request
    028{
    029    /**
    030     * Gets the {@link Session}. If create is false and the session has not be created previously, returns null. Also,
    031     * if the session is invalidated and create is false, returns null. Invoking this method with true, when the session exists but has
    032     * been invalidated, will force the creation of a new session.
    033     *
    034     * @param create
    035     *         true to force the creation of the session
    036     * @return the session (or null if create is false the session has not been previously created)
    037     */
    038    Session getSession(boolean create);
    039
    040    /**
    041     * Returns the context path. This always starts with a "/" character and does not end with one, with the exception
    042     * of servlets in the root context, which return the empty string.
    043     *
    044     * @deprecated in 5.4, inject the value for symbol {@link org.apache.tapestry5.SymbolConstants#CONTEXT_PATH} instead
    045     */
    046    String getContextPath();
    047
    048    /**
    049     * Returns a list of query parameter names, in alphabetical order.
    050     */
    051    List<String> getParameterNames();
    052
    053    /**
    054     * Returns the query parameter value for the given name. Returns null if no such parameter is in the request. For a
    055     * multi-valued parameter, returns just the first value.
    056     */
    057    String getParameter(String name);
    058
    059    /**
    060     * Returns the parameter values for the given name. Returns null if no such parameter is in the request.
    061     */
    062    String[] getParameters(String name);
    063
    064    /**
    065     * Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the
    066     * query parameters. It doesn't include the context path.
    067     */
    068    String getPath();
    069
    070    /**
    071     * Returns the locale of the client as determined from the request headers.
    072     */
    073    Locale getLocale();
    074
    075    /**
    076     * Returns the names of all headers in the request.
    077     */
    078    List<String> getHeaderNames();
    079
    080    /**
    081     * Returns the value of the specified request header as a <code>long</code> value that represents a
    082     * <code>Date</code> object. Use this method with headers that contain dates, such as <code>If-Modified-Since</code>
    083     * .
    084     * <p/>
    085     * The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case
    086     * insensitive.
    087     * <p/>
    088     * If the request did not have a header of the specified name, this method returns -1. If the header can't be
    089     * converted to a date, the method throws an <code>IllegalArgumentException</code>.
    090     *
    091     * @param name
    092     *         a <code>String</code> specifying the name of the header
    093     * @return a <code>long</code> value representing the date specified in the header expressed as the number of
    094     *         milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest
    095     * @throws IllegalArgumentException
    096     *         If the header value can't be converted to a date
    097     */
    098    long getDateHeader(String name);
    099
    100    /**
    101     * Returns the named header as a string, or null if not found.
    102     */
    103    String getHeader(String name);
    104
    105    /**
    106     * Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior). Ajax
    107     * action requests may behave quite differently than ordinary, page-based requests. This implementation currently
    108     * depends on the client side setting a header: <strong>X-Requested-With=XMLHttpRequest</strong> (this is what
    109     * Prototype does).
    110     *
    111     * @return true if the request has an XmlHttpRequest origin
    112     */
    113    boolean isXHR();
    114
    115    /**
    116     * Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
    117     *
    118     * @return a boolean indicating if the request was made using a secure channel
    119     */
    120    public boolean isSecure();
    121
    122    /**
    123     * Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the
    124     * <code>Host</code> header, if any, or the resolved server name, or the server IP address.
    125     *
    126     * @return the name of the server
    127     */
    128    public String getServerName();
    129
    130    /**
    131     * Checks whether the requested session ID is still valid.
    132     *
    133     * @return true if the request included a session id that is still active, false if the included session id has
    134     *         expired
    135     */
    136    boolean isRequestedSessionIdValid();
    137
    138    /**
    139     * Returns the value of the named attribute as an <code>Object</code>, or <code>null</code> if no attribute of the
    140     * given name exists. Because this method is a wrapper around
    141     * {@link javax.servlet.ServletRequest#getAttribute(String)},
    142     * it is case <em>sensitive</em> (unlike most of Tapestry).
    143     *
    144     * @param name
    145     *         a <code>String</code> specifying the name of the attribute
    146     * @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does
    147     *         not exist
    148     */
    149    Object getAttribute(String name);
    150
    151    /**
    152     * Returns a sorted list of attribute names.
    153     *
    154     * @since 5.4
    155     */
    156    List<String> getAttributeNames();
    157
    158
    159    /**
    160     * Stores an attribute in this request. Attributes are reset between requests (and remember that in Tapestry, there
    161     * is usually two requests per operation: the action request that redirects to a render request).
    162     *
    163     * @param name
    164     *         a <code>String</code> specifying the name of the attribute
    165     * @param value
    166     *         the <code>Object</code> to be stored, or null to remove the attribute
    167     */
    168    void setAttribute(String name, Object value);
    169
    170    /**
    171     * Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
    172     *
    173     * @return a string specifying the name of the method with which this request was made
    174     */
    175    String getMethod();
    176
    177    /**
    178     * Returns the Internet Protocol (IP) port number of the interface
    179     * on which the request was received.
    180     *
    181     * @return an integer specifying the port number
    182     * @since 5.2.0
    183     */
    184    int getLocalPort();
    185
    186    /**
    187     * Returns the port number to which the request was sent.
    188     * It is the value of the part after ":" in the <code>Host</code> header, if any, or the server port where the
    189     * client connection
    190     * was accepted on.
    191     *
    192     * @return an integer specifying the port number
    193     * @since 5.2.5
    194     */
    195    int getServerPort();
    196
    197    /**
    198     * Returns the fully qualified name of the client
    199     * or the last proxy that sent the request.
    200     * If the engine cannot or chooses not to resolve the hostname
    201     * (to improve performance), this method returns the dotted-string form of
    202     * the IP address.
    203     *
    204     * @return a <code>String</code> containing the fully
    205     *         qualified name of the client
    206     * @since 5.3
    207     */
    208    String getRemoteHost();
    209
    210    /**
    211     * Returns true if the request specified a session, and that session has been invalidated.
    212     *
    213     * @return true if session was invalidated during this request
    214     * @since 5.4
    215     */
    216    boolean isSessionInvalidated();
    217}