1 /*
2 * ========================================================================
3 *
4 * Licensed to the Apache Software Foundation (ASF) under one or more
5 * contributor license agreements. See the NOTICE file distributed with
6 * this work for additional information regarding copyright ownership.
7 * The ASF licenses this file to You under the Apache License, Version 2.0
8 * (the "License"); you may not use this file except in compliance with
9 * the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 *
19 * ========================================================================
20 */
21 package org.apache.cactus;
22
23 import java.io.InputStream;
24 import java.util.Enumeration;
25 import java.util.Vector;
26
27 import org.apache.cactus.client.authentication.Authentication;
28
29 /**
30 * Contains HTTP request data for a Cactus test case.
31 *
32 * @version $Id: WebRequest.java 238991 2004-05-22 11:34:50Z vmassol $
33 */
34 public interface WebRequest extends Request
35 {
36 /**
37 * GET Method identifier.
38 */
39 String GET_METHOD = "GET";
40
41 /**
42 * POST Method identifier.
43 */
44 String POST_METHOD = "POST";
45
46 /**
47 * Sets the content type that will be set in the http request.
48 *
49 * @param theContentType the content type
50 */
51 void setContentType(String theContentType);
52
53 /**
54 * @return the content type that will be set in the http request
55 */
56 String getContentType();
57
58 /**
59 * Allow the user to send arbitrary data in the request body.
60 *
61 * @param theDataStream the stream on which the data are put by the user
62 */
63 void setUserData(InputStream theDataStream);
64
65 /**
66 * @return the data stream set up by the user
67 */
68 InputStream getUserData();
69
70 /**
71 * Adds a parameter to the request. It is possible to add several times the
72 * the same parameter name, but with different value (the same as for the
73 * <code>HttpServletRequest</code>).
74 *
75 * @param theName the parameter's name
76 * @param theValue the parameter's value
77 * @param theMethod GET_METHOD or POST_METHOD. If GET_METHOD then the
78 * parameter will be sent in the query string of the URL. If
79 * POST_METHOD, it will be sent as a parameter in the request body.
80 */
81 void addParameter(String theName, String theValue, String theMethod);
82
83 /**
84 * Adds a parameter to the request. The parameter is added to the query
85 * string of the URL.
86 *
87 * @param theName the parameter's name
88 * @param theValue the parameter's value
89 *
90 * @see #addParameter(String, String, String)
91 */
92 void addParameter(String theName, String theValue);
93
94 /**
95 * @return the parameter names that will be passed in the request body
96 * (POST)
97 */
98 Enumeration getParameterNamesPost();
99
100 /**
101 * @return the parameter names that will be passed in the URL (GET)
102 */
103 Enumeration getParameterNamesGet();
104
105 /**
106 * Returns the first value corresponding to this parameter's name (provided
107 * this parameter is passed in the URL).
108 *
109 * @param theName the parameter's name
110 * @return the first value corresponding to this parameter's name or null
111 * if not found in the list of parameters to be sent in the URL
112 */
113 String getParameterGet(String theName);
114
115 /**
116 * Returns the first value corresponding to this parameter's name (provided
117 * this parameter is passed in the request body - POST).
118 *
119 * @param theName the parameter's name
120 * @return the first value corresponding to this parameter's name or null
121 * if not found in the list of parameters to be sent in the request
122 * body
123 */
124 String getParameterPost(String theName);
125
126 /**
127 * Returns all the values corresponding to this parameter's name (provided
128 * this parameter is passed in the URL).
129 *
130 * @param theName the parameter's name
131 * @return the first value corresponding to this parameter's name or null
132 * if not found in the list of parameters to be sent in the URL
133 */
134 String[] getParameterValuesGet(String theName);
135
136 /**
137 * Returns all the values corresponding to this parameter's name (provided
138 * this parameter is passed in the request body - POST).
139 *
140 * @param theName the parameter's name
141 * @return the first value corresponding to this parameter's name or null
142 * if not found in the list of parameters to be sent in the request
143 * body
144 */
145 String[] getParameterValuesPost(String theName);
146
147 /**
148 * Adds a cookie to the request. The cookie will be created with a
149 * default localhost domain. If you need to specify a domain for the cookie,
150 * use the {@link #addCookie(String, String, String)} method or the method
151 * {@link #addCookie(Cookie)}.
152 *
153 * @param theName the cookie's name
154 * @param theValue the cookie's value
155 */
156 void addCookie(String theName, String theValue);
157
158 /**
159 * Adds a cookie to the request. The cookie will be created with the
160 * domain passed as parameter (i.e. the cookie will get sent only to
161 * requests to that domain).
162 *
163 * Note that the domain must match either the redirector host
164 * (specified in <code>cactus.properties</code>) or the host set
165 * using <code>setURL()</code>.
166 *
167 * @param theDomain the cookie domain
168 * @param theName the cookie name
169 * @param theValue the cookie value
170 */
171 void addCookie(String theDomain, String theName, String theValue);
172
173 /**
174 * Adds a cookie to the request.
175 *
176 * Note that the domain must match either the redirector host
177 * (specified in <code>cactus.properties</code>) or the host set
178 * using <code>setURL()</code>.
179 *
180 * @param theCookie the cookie to add
181 */
182 void addCookie(Cookie theCookie);
183
184 /**
185 * @return the cookies (vector of <code>Cookie</code> objects)
186 */
187 Vector getCookies();
188
189 /**
190 * Adds a header to the request. Supports adding several values for the
191 * same header name.
192 *
193 * @param theName the header's name
194 * @param theValue the header's value
195 */
196 void addHeader(String theName, String theValue);
197
198 /**
199 * @return the header names
200 */
201 Enumeration getHeaderNames();
202
203 /**
204 * Returns the first value corresponding to this header's name.
205 *
206 * @param theName the header's name
207 * @return the first value corresponding to this header's name or null if
208 * not found
209 */
210 String getHeader(String theName);
211
212 /**
213 * Returns all the values associated with this header's name.
214 *
215 * @param theName the header's name
216 * @return the values corresponding to this header's name or null if not
217 * found
218 */
219 String[] getHeaderValues(String theName);
220
221 /**
222 * Sets the authentication object that will configure the http request.
223 *
224 * @param theAuthentication the authentication object
225 */
226 void setAuthentication(Authentication theAuthentication);
227
228 /**
229 * @return the authentication that will configure the http request
230 */
231 Authentication getAuthentication();
232
233 /**
234 * Override the redirector Name defined in <code>cactus.properties</code>.
235 * This is useful to define a per test case Name (for example, if some
236 * test case need to have authentication turned on and not other tests,
237 * etc).
238 *
239 * @param theRedirectorName the new redirector Name to use
240 */
241 void setRedirectorName(String theRedirectorName);
242
243 /**
244 * @return the overriden redirector Name or null if none has been defined
245 */
246 String getRedirectorName();
247
248 /**
249 * @param isAutomaticSession whether the redirector servlet will
250 * automatically create the HTTP session or not. Default is true.
251 */
252 void setAutomaticSession(boolean isAutomaticSession);
253
254 /**
255 * @return true if session will be automatically created for the user or
256 * false otherwise.
257 */
258 boolean getAutomaticSession();
259
260 /**
261 * Sets the simulated URL. A URL is of the form :<br>
262 * <code><pre><b>
263 * URL = "http://" + serverName (including port) + requestURI ? queryString
264 * <br>requestURI = contextPath + servletPath + pathInfo
265 * </b></pre></code>
266 * From the Servlet 2.2 specification :<br>
267 * <code><pre><ul>
268 * <li><b>Context Path</b>: The path prefix associated with the
269 * ServletContext that this servlet is a part of. If this context is the
270 * default context rooted at the base of the web server's URL namespace,
271 * this path will be an empty string. Otherwise, this path starts with a
272 * character but does not end with a character.</li>
273 * <li><b>Servlet Path</b>: The path section that directly corresponds to
274 * the mapping which activated this request. This path starts with a
275 * character.</li>
276 * <li><b>PathInfo</b>: The part of the request path that is not part of the
277 * Context Path or the Servlet Path.</li>
278 * </ul></pre></code>
279 *
280 * @param theServerName the server name (and port) in the URL to simulate,
281 * i.e. this is the name that will be returned by the
282 * <code>HttpServletRequest.getServerName()</code> and
283 * <code>HttpServletRequest.getServerPort()</code>.
284 * @param theContextPath the webapp context path in the URL to simulate,
285 * i.e. this is the name that will be returned by the
286 * <code>HttpServletRequest.getContextPath()</code>.
287 * Can be null. Format: "/" + name or an empty string
288 * for the default context.
289 * @param theServletPath the servlet path in the URL to simulate,
290 * i.e. this is the name that will be returned by the
291 * <code>HttpServletRequest.getServletPath()</code>.
292 * Can be null. Format : "/" + name.
293 * @param thePathInfo the path info in the URL to simulate, i.e. this is
294 * the name that will be returned by the
295 * <code>HttpServletRequest.getPathInfo()</code>. Can
296 * be null. Format : "/" + name.
297 * @param theQueryString the Query string in the URL to simulate, i.e. this
298 * is the string that will be returned by the
299 * <code>HttpServletResquest.getQueryString()</code>.
300 * Can be null.
301 */
302 void setURL(String theServerName, String theContextPath,
303 String theServletPath, String thePathInfo, String theQueryString);
304
305 /**
306 * @return the simulated URL
307 */
308 ServletURL getURL();
309
310 /**
311 * Gets an HTTP session id by calling the server side and retrieving
312 * the jsessionid cookie in the HTTP response. This is achieved by
313 * calling the Cactus redirector used by the current test case.
314 *
315 * @return the HTTP session id as a <code>HttpSessionCookie</code> object
316 */
317 HttpSessionCookie getSessionCookie();
318 }