WebRequest


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