1 // Copyright 2006, 2007, 2008 The Apache Software Foundation
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 package org.apache.tapestry5.services;
16
17 import java.util.List;
18 import java.util.Locale;
19
20 /**
21 * Generic version of {@link javax.servlet.http.HttpServletRequest}, used to encapsulate the Servlet API version, and to
22 * help bridge the differences between Servlet API and Porlet API.
23 * <p/>
24 * <p/>
25 * The Request service is a {@linkplain org.apache.tapestry5.ioc.services.PropertyShadowBuilder shadow} of the current
26 * thread's request.
27 */
28 public interface Request
29 {
30 /**
31 * Gets the {@link Session}. If create is false and the session has not be created previously, returns null.
32 *
33 * @param create true to force the creation of the session
34 * @return the session (or null if create is false the session has not been previously created)
35 */
36 Session getSession(boolean create);
37
38 /**
39 * Returns the context path. This always starts with a "/" character and does not end with one, with the exception
40 * of servlets in the root context, which return the empty string.
41 */
42 String getContextPath();
43
44 /**
45 * Returns a list of query parameter names, in alphabetical order.
46 */
47 List<String> getParameterNames();
48
49 /**
50 * Returns the query parameter value for the given name. Returns null if no such parameter is in the request. For a
51 * multi-valued parameter, returns just the first value.
52 */
53 String getParameter(String name);
54
55 /**
56 * Returns the parameter values for the given name. Returns null if no such parameter is in the request.
57 */
58 String[] getParameters(String name);
59
60 /**
61 * Returns the path portion of the request, which starts with a "/" and contains everything up to the start of the
62 * query parameters. It doesn't include the context path.
63 */
64 String getPath();
65
66 /**
67 * Returns the locale of the client as determined from the request headers.
68 */
69 Locale getLocale();
70
71 /**
72 * Returns the names of all headers in the request.
73 */
74 List<String> getHeaderNames();
75
76 /**
77 * Returns the value of the specified request header as a <code>long</code> value that represents a
78 * <code>Date</code> object. Use this method with headers that contain dates, such as
79 * <code>If-Modified-Since</code>.
80 * <p/>
81 * The date is returned as the number of milliseconds since January 1, 1970 GMT. The header name is case
82 * insensitive.
83 * <p/>
84 * If the request did not have a header of the specified name, this method returns -1. If the header can't be
85 * converted to a date, the method throws an <code>IllegalArgumentException</code>.
86 *
87 * @param name a <code>String</code> specifying the name of the header
88 * @return a <code>long</code> value representing the date specified in the header expressed as the number of
89 * milliseconds since January 1, 1970 GMT, or -1 if the named header was not included with the reqest
90 * @throws IllegalArgumentException If the header value can't be converted to a date
91 */
92 long getDateHeader(String name);
93
94 /**
95 * Returns the named header as a string, or null if not found.
96 */
97 String getHeader(String name);
98
99 /**
100 * Returns true if the request originated on the client using XmlHttpRequest (the core of any Ajax behavior). Ajax
101 * action requests may behave quite differently than ordinary, page-based requests. This implementation currently
102 * depends on the client side setting a header: <strong>X-Requested-With=XMLHttpRequest</strong> (this is what
103 * Prototype does).
104 *
105 * @return true if the request has an XmlHttpRequest origin
106 */
107 boolean isXHR();
108
109 /**
110 * Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
111 *
112 * @return a boolean indicating if the request was made using a secure channel
113 */
114 public boolean isSecure();
115
116 /**
117 * Returns the host name of the server to which the request was sent. It is the value of the part before ":" in the
118 * <code>Host</code> header, if any, or the resolved server name, or the server IP address.
119 *
120 * @return the name of the server
121 */
122 public String getServerName();
123
124 /**
125 * Checks whether the requested session ID is still valid.
126 *
127 * @return true if the request included a session id that is still active, false if the included session id has
128 * expired
129 */
130 boolean isRequestedSessionIdValid();
131
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 {@link javax.servlet.ServletRequest#getAttribute(String)},
136 * it is case <em>sensitive</em> (unlike most of Tapestry).
137 *
138 * @param name a <code>String</code> specifying the name of the attribute
139 * @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does
140 * not exist
141 */
142 Object getAttribute(String name);
143
144 /**
145 * Stores an attribute in this request. Attributes are reset between requests (and remember that in Tapestry, there
146 * is usually two requests per operation: the action request that redirects to a render request).
147 *
148 * @param name a <code>String</code> specifying the name of the attribute
149 * @param value the <code>Object</code> to be stored, or null to remove the attribute
150 */
151 void setAttribute(String name, Object value);
152
153 /**
154 * Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
155 *
156 * @return a string specifying the name of the method with which this request was made
157 */
158 public String getMethod();
159 }