1 /*
2 * Copyright 1999-2002,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.apache.commons.latka.http;
18
19 import java.net.URL;
20 import java.io.IOException;
21
22 /**
23 * A Latka Request represents a request from an HTTP server.
24 *
25 * @author <a href="mailto:dsale@us.britannica.com">Doug Sale</a>
26 * @author <a href="mailto:mdelagra@us.britannica.com">Morgan Delagrange</a>
27 * @author dIon Gillard
28 */
29 public interface Request {
30
31 /** An integer representing the HTTP GET method */
32 public static final int HTTP_METHOD_GET = 0;
33 /** An integer representing the HTTP POST method */
34 public static final int HTTP_METHOD_POST = 1;
35 /** An integer representing the HTTP POST method */
36 public static final int HTTP_METHOD_HEAD = 2;
37
38 /**
39 * Execute this HTTP request. In the event of a 301 or 302,
40 * this method may need to create a new Request,
41 * due to an idiosyncracy of
42 * HttpClient. In that case, the Response.getRequest()
43 * method will return the actual Request that was executed.
44 * This will probably be fixed at some point in the future.
45 *
46 * @return a Response object represnting the HTTP response to the request
47 *
48 * @throws IOException if the remote server could not be reached
49 */
50 Response execute() throws IOException;
51
52 /**
53 * Assigns a text label to this request. This label
54 * will be made available to a LatkaEventListener
55 * during a test's execution
56 *
57 * @return the label associated with this request
58 */
59 String getLabel();
60
61 /**
62 * Gets the URL that Latka will attempt to contact. Note:
63 * since Latka will respect most redirects, this may not
64 * be the URL that returns the actual response.
65 *
66 * @return the URL associated with this HTTP request
67 */
68 URL getURL();
69
70 /**
71 * Associate a parameter with this request.
72 *
73 * @param name the name of the parameter
74 * @param value the value of the parameter
75 *
76 */
77 void addParameter(String name, String value);
78
79 /**
80 * Set all the parameters for the request. Overrides
81 * any parameters that have been already set by addParameter();
82 *
83 * @param parameters
84 * all parameters for this request
85 */
86 void setParameters(Parameters parameters);
87
88 /**
89 * Get the parameters for the request, so that they can
90 * be copied to another request if necessary.
91 *
92 * @return parameters for this request
93 */
94 Parameters getParameters();
95
96 /**
97 * Sets a request header.
98 *
99 * @param headerName header name
100 * @param headerValue header value or null for a null header
101 */
102 void addHeader(String headerName, String headerValue);
103
104 /**
105 * Set all the headers for the request. Overrides
106 * any headers that have been already set by addHeader();
107 *
108 * @param requestHeaders
109 * all headers for this request
110 */
111 void setHeaders(RequestHeaders requestHeaders);
112
113 /**
114 * Get the headers for the request, so that they can
115 * be copied to another request if necessary.
116 *
117 * @return headers for this request
118 */
119 RequestHeaders getHeaders();
120
121 // getHeader method purposely ommitted. HttpClient does not retain
122 // header information after the request is submitted.
123
124 /**
125 * Retrieve the session associated with this request.
126 *
127 * @return a <code>Session</code> object
128 */
129 Session getSession();
130
131 /**
132 * The amount of time it took to execute the
133 * request in milliseconds, or -1 if the request has not
134 * been executed successfully
135 *
136 * @return time it took to execute the request in millis
137 */
138 int getRequestTiming();
139
140 /**
141 * Sets the basic authentication credentials for this request,
142 * if any.
143 *
144 * @param credentials user's identification
145 */
146 void setCredentials(Credentials credentials);
147
148 /**
149 * Return the credentials for this request
150 *
151 * @return Request credentials
152 */
153 Credentials getCredentials();
154
155 /**
156 * Whether or not this request will instruct HttpClient
157 * to follow local redirects automatically.
158 *
159 * @return true if HttpClient will redirect a 301 or 302 response
160 */
161 boolean followRedirects();
162
163 /**
164 * Return the constant representing the HTTP method
165 * to use in this request
166 *
167 * @return HTTP method for this request
168 */
169 int getMethod();
170
171 /**
172 * Set the request body for a manual POST. You may not
173 * both set the request body and add parameters.
174 *
175 * @param body Body to POST
176 */
177 void setRequestBody(String body);
178
179 /**
180 * Sets the version of HTTP that is used in the request.
181 * If the version of HTTP specified is not 1.0 or 1.1,
182 * then the default of 1.1 will be used.
183 *
184 * @param version HTTP version.
185 */
186 void setVersion(String version);
187
188 /**
189 * Get the HTTP version to use in this request
190 *
191 * @return HTTP version for the request
192 */
193 String getVersion();
194
195 }