001: /*
002: * ========================================================================
003: *
004: * Copyright 2001-2003 The Apache Software Foundation.
005: *
006: * Licensed under the Apache License, Version 2.0 (the "License");
007: * you may not use this file except in compliance with the License.
008: * You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS,
014: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015: * See the License for the specific language governing permissions and
016: * limitations under the License.
017: *
018: * ========================================================================
019: */
020: package org.apache.cactus;
021:
022: import java.io.InputStream;
023: import java.util.Enumeration;
024: import java.util.Vector;
025:
026: import org.apache.cactus.client.authentication.Authentication;
027:
028: /**
029: * Contains HTTP request data for a Cactus test case.
030: *
031: * @version $Id: WebRequest.java 238991 2004-05-22 11:34:50Z vmassol $
032: */
033: public interface WebRequest extends Request {
034: /**
035: * GET Method identifier.
036: */
037: String GET_METHOD = "GET";
038:
039: /**
040: * POST Method identifier.
041: */
042: String POST_METHOD = "POST";
043:
044: /**
045: * Sets the content type that will be set in the http request
046: *
047: * @param theContentType the content type
048: */
049: void setContentType(String theContentType);
050:
051: /**
052: * @return the content type that will be set in the http request
053: */
054: String getContentType();
055:
056: /**
057: * Allow the user to send arbitrary data in the request body
058: *
059: * @param theDataStream the stream on which the data are put by the user
060: */
061: void setUserData(InputStream theDataStream);
062:
063: /**
064: * @return the data stream set up by the user
065: */
066: InputStream getUserData();
067:
068: /**
069: * Adds a parameter to the request. It is possible to add several times the
070: * the same parameter name, but with different value (the same as for the
071: * <code>HttpServletRequest</code>).
072: *
073: * @param theName the parameter's name
074: * @param theValue the parameter's value
075: * @param theMethod GET_METHOD or POST_METHOD. If GET_METHOD then the
076: * parameter will be sent in the query string of the URL. If
077: * POST_METHOD, it will be sent as a parameter in the request body.
078: */
079: void addParameter(String theName, String theValue, String theMethod);
080:
081: /**
082: * Adds a parameter to the request. The parameter is added to the query
083: * string of the URL.
084: *
085: * @param theName the parameter's name
086: * @param theValue the parameter's value
087: *
088: * @see #addParameter(String, String, String)
089: */
090: void addParameter(String theName, String theValue);
091:
092: /**
093: * @return the parameter names that will be passed in the request body
094: * (POST)
095: */
096: Enumeration getParameterNamesPost();
097:
098: /**
099: * @return the parameter names that will be passed in the URL (GET)
100: */
101: Enumeration getParameterNamesGet();
102:
103: /**
104: * Returns the first value corresponding to this parameter's name (provided
105: * this parameter is passed in the URL).
106: *
107: * @param theName the parameter's name
108: * @return the first value corresponding to this parameter's name or null
109: * if not found in the list of parameters to be sent in the URL
110: */
111: String getParameterGet(String theName);
112:
113: /**
114: * Returns the first value corresponding to this parameter's name (provided
115: * this parameter is passed in the request body - POST).
116: *
117: * @param theName the parameter's name
118: * @return the first value corresponding to this parameter's name or null
119: * if not found in the list of parameters to be sent in the request
120: * body
121: */
122: String getParameterPost(String theName);
123:
124: /**
125: * Returns all the values corresponding to this parameter's name (provided
126: * this parameter is passed in the URL).
127: *
128: * @param theName the parameter's name
129: * @return the first value corresponding to this parameter's name or null
130: * if not found in the list of parameters to be sent in the URL
131: */
132: String[] getParameterValuesGet(String theName);
133:
134: /**
135: * Returns all the values corresponding to this parameter's name (provided
136: * this parameter is passed in the request body - POST).
137: *
138: * @param theName the parameter's name
139: * @return the first value corresponding to this parameter's name or null
140: * if not found in the list of parameters to be sent in the request
141: * body
142: */
143: String[] getParameterValuesPost(String theName);
144:
145: /**
146: * Adds a cookie to the request. The cookie will be created with a
147: * default localhost domain. If you need to specify a domain for the cookie,
148: * use the {@link #addCookie(String, String, String)} method or the method
149: * {@link #addCookie(Cookie)}.
150: *
151: * @param theName the cookie's name
152: * @param theValue the cookie's value
153: */
154: void addCookie(String theName, String theValue);
155:
156: /**
157: * Adds a cookie to the request. The cookie will be created with the
158: * domain passed as parameter (i.e. the cookie will get sent only to
159: * requests to that domain).
160: *
161: * Note that the domain must match either the redirector host
162: * (specified in <code>cactus.properties</code>) or the host set
163: * using <code>setURL()</code>.
164: *
165: * @param theDomain the cookie domain
166: * @param theName the cookie name
167: * @param theValue the cookie value
168: */
169: void addCookie(String theDomain, String theName, String theValue);
170:
171: /**
172: * Adds a cookie to the request.
173: *
174: * Note that the domain must match either the redirector host
175: * (specified in <code>cactus.properties</code>) or the host set
176: * using <code>setURL()</code>.
177: *
178: * @param theCookie the cookie to add
179: */
180: void addCookie(Cookie theCookie);
181:
182: /**
183: * @return the cookies (vector of <code>Cookie</code> objects)
184: */
185: Vector getCookies();
186:
187: /**
188: * Adds a header to the request. Supports adding several values for the
189: * same header name.
190: *
191: * @param theName the header's name
192: * @param theValue the header's value
193: */
194: void addHeader(String theName, String theValue);
195:
196: /**
197: * @return the header names
198: */
199: Enumeration getHeaderNames();
200:
201: /**
202: * Returns the first value corresponding to this header's name.
203: *
204: * @param theName the header's name
205: * @return the first value corresponding to this header's name or null if
206: * not found
207: */
208: String getHeader(String theName);
209:
210: /**
211: * Returns all the values associated with this header's name.
212: *
213: * @param theName the header's name
214: * @return the values corresponding to this header's name or null if not
215: * found
216: */
217: String[] getHeaderValues(String theName);
218:
219: /**
220: * Sets the authentication object that will configure the http request
221: *
222: * @param theAuthentication the authentication object
223: */
224: void setAuthentication(Authentication theAuthentication);
225:
226: /**
227: * @return the authentication that will configure the http request
228: */
229: Authentication getAuthentication();
230:
231: /**
232: * Override the redirector Name defined in <code>cactus.properties</code>.
233: * This is useful to define a per test case Name (for example, if some
234: * test case need to have authentication turned on and not other tests,
235: * etc).
236: *
237: * @param theRedirectorName the new redirector Name to use
238: */
239: void setRedirectorName(String theRedirectorName);
240:
241: /**
242: * @return the overriden redirector Name or null if none has been defined
243: */
244: String getRedirectorName();
245:
246: /**
247: * @param isAutomaticSession whether the redirector servlet will
248: * automatically create the HTTP session or not. Default is true.
249: */
250: void setAutomaticSession(boolean isAutomaticSession);
251:
252: /**
253: * @return true if session will be automatically created for the user or
254: * false otherwise.
255: */
256: boolean getAutomaticSession();
257:
258: /**
259: * Sets the simulated URL. A URL is of the form :<br>
260: * <code><pre><b>
261: * URL = "http://" + serverName (including port) + requestURI ? queryString
262: * <br>requestURI = contextPath + servletPath + pathInfo
263: * </b></pre></code>
264: * From the Servlet 2.2 specification :<br>
265: * <code><pre><ul>
266: * <li><b>Context Path</b>: The path prefix associated with the
267: * ServletContext that this servlet is a part of. If this context is the
268: * default context rooted at the base of the web server's URL namespace,
269: * this path will be an empty string. Otherwise, this path starts with a
270: * character but does not end with a character.</li>
271: * <li><b>Servlet Path</b>: The path section that directly corresponds to
272: * the mapping which activated this request. This path starts with a
273: * character.</li>
274: * <li><b>PathInfo</b>: The part of the request path that is not part of the
275: * Context Path or the Servlet Path.</li>
276: * </ul></pre></code>
277: *
278: * @param theServerName the server name (and port) in the URL to simulate,
279: * i.e. this is the name that will be returned by the
280: * <code>HttpServletRequest.getServerName()</code> and
281: * <code>HttpServletRequest.getServerPort()</code>.
282: * @param theContextPath the webapp context path in the URL to simulate,
283: * i.e. this is the name that will be returned by the
284: * <code>HttpServletRequest.getContextPath()</code>.
285: * Can be null. Format: "/" + name or an empty string
286: * for the default context.
287: * @param theServletPath the servlet path in the URL to simulate,
288: * i.e. this is the name that will be returned by the
289: * <code>HttpServletRequest.getServletPath()</code>.
290: * Can be null. Format : "/" + name.
291: * @param thePathInfo the path info in the URL to simulate, i.e. this is
292: * the name that will be returned by the
293: * <code>HttpServletRequest.getPathInfo()</code>. Can
294: * be null. Format : "/" + name.
295: * @param theQueryString the Query string in the URL to simulate, i.e. this
296: * is the string that will be returned by the
297: * <code>HttpServletResquest.getQueryString()</code>.
298: * Can be null.
299: */
300: void setURL(String theServerName, String theContextPath,
301: String theServletPath, String thePathInfo,
302: 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: }
|