2011/08/05 - Jakarta Cactus has been retired.

For more information, please explore the Attic.

View Javadoc

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 }