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