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