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
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 * <p/>
025 * The Request service is a {@linkplain org.apache.tapestry5.ioc.services.PropertyShadowBuilder shadow} of the current
026 * thread's request.
027 */
028public 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}