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 }