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    }