1 /*
2 * $Id: Request.java 1375743 2012-08-21 20:05:58Z nlebas $
3 *
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21 package org.apache.tiles.request;
22
23 import java.io.IOException;
24 import java.io.OutputStream;
25 import java.io.PrintWriter;
26 import java.io.Writer;
27 import java.util.List;
28 import java.util.Locale;
29 import java.util.Map;
30
31 import org.apache.tiles.request.attribute.Addable;
32
33
34 /**
35 * Encapsulation of request information.
36 *
37 * @version $Rev: 1375743 $ $Date: 2012-08-22 06:05:58 +1000 (Wed, 22 Aug 2012) $
38 */
39 public interface Request {
40
41 /** the name of the (mandatory) "application" scope */
42 static String APPLICATION_SCOPE = "application";
43
44 /** the name of the "request" context */
45 static String REQUEST_SCOPE = "request";
46
47 /**
48 * Return an immutable Map that maps header names to the first (or only)
49 * header value (as a String).
50 *
51 * @return The header map.
52 */
53 Map<String, String> getHeader();
54
55 /**
56 * Return an immutable Map that maps header names to the set of all values
57 * specified in the request (as a String array). Header names must be
58 * matched in a case-insensitive manner.
59 *
60 * @return The header values map.
61 */
62 Map<String, String[]> getHeaderValues();
63
64 /**
65 * Return an Addable object that can be used to write headers to the response.
66 *
67 * @return An Addable object.
68 */
69 Addable<String> getResponseHeaders();
70
71 /**
72 * Returns a context map, given the scope name.
73 * This method always return a map for all the scope names returned by
74 * getAvailableScopes(). That map may be writable, or immutable, depending
75 * on the implementation.
76 *
77 * @param scope The name of the scope.
78 * @return The context.
79 */
80 Map<String, Object> getContext(String scope);
81
82 /**
83 * Returns all available scopes.
84 * The scopes are ordered according to their lifetime,
85 * the innermost, shorter lived scope appears first,
86 * and the outermost, longer lived scope appears last.
87 * Besides, the scopes "request" and "application" always included
88 * in the list.
89 *
90 * @return All the available scopes.
91 */
92 List<String> getAvailableScopes();
93
94 /**
95 * Returns the associated application context.
96 *
97 * @return The application context associated to this request.
98 */
99 ApplicationContext getApplicationContext();
100
101 /**
102 * Returns an output stream to be used to write directly in the response.
103 *
104 * @return The output stream that writes in the response.
105 * @throws IOException If something goes wrong when getting the output stream.
106 */
107 OutputStream getOutputStream() throws IOException;
108
109 /**
110 * Returns a writer to be used to write directly in the response.
111 *
112 * @return The writer that writes in the response.
113 * @throws IOException If something goes wrong when getting the writer.
114 */
115 Writer getWriter() throws IOException;
116
117 /**
118 * Returns a print writer to be used to write directly in the response.
119 *
120 * @return The print writer that writes in the response.
121 * @throws IOException If something goes wrong when getting the print
122 * writer.
123 */
124 PrintWriter getPrintWriter() throws IOException;
125
126 /**
127 * Checks if the response has been committed.
128 *
129 * @return <code>true</code> only if the response has been committed.
130 */
131 boolean isResponseCommitted();
132
133 /**
134 * Return an immutable Map that maps request parameter names to the first
135 * (or only) value (as a String).
136 *
137 * @return The parameter map.
138 */
139 Map<String, String> getParam();
140
141 /**
142 * Return an immutable Map that maps request parameter names to the set of
143 * all values (as a String array).
144 *
145 * @return The parameter values map.
146 */
147 Map<String, String[]> getParamValues();
148
149 /**
150 * Return the preferred Locale in which the client will accept content.
151 *
152 * @return The current request locale. It is the locale of the request
153 * object itself and it is NOT the locale that the user wants to use. See
154 * {@link org.apache.tiles.locale.LocaleResolver} to implement strategies to
155 * resolve locales.
156 */
157 Locale getRequestLocale();
158
159 /**
160 * Determine whether or not the specified user is in the given role.
161 * @param role the role to check against.
162 * @return <code>true</code> if the user is in the given role.
163 */
164 boolean isUserInRole(String role);
165
166 }