001 /*
002 * Copyright 1999-2002,2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.apache.commons.latka.http;
018
019 import java.net.URL;
020 import java.io.IOException;
021
022 /**
023 * A Latka Request represents a request from an HTTP server.
024 *
025 * @author <a href="mailto:dsale@us.britannica.com">Doug Sale</a>
026 * @author <a href="mailto:mdelagra@us.britannica.com">Morgan Delagrange</a>
027 * @author dIon Gillard
028 */
029 public interface Request {
030
031 /** An integer representing the HTTP GET method */
032 public static final int HTTP_METHOD_GET = 0;
033 /** An integer representing the HTTP POST method */
034 public static final int HTTP_METHOD_POST = 1;
035 /** An integer representing the HTTP POST method */
036 public static final int HTTP_METHOD_HEAD = 2;
037
038 /**
039 * Execute this HTTP request. In the event of a 301 or 302,
040 * this method may need to create a new Request,
041 * due to an idiosyncracy of
042 * HttpClient. In that case, the Response.getRequest()
043 * method will return the actual Request that was executed.
044 * This will probably be fixed at some point in the future.
045 *
046 * @return a Response object represnting the HTTP response to the request
047 *
048 * @throws IOException if the remote server could not be reached
049 */
050 Response execute() throws IOException;
051
052 /**
053 * Assigns a text label to this request. This label
054 * will be made available to a LatkaEventListener
055 * during a test's execution
056 *
057 * @return the label associated with this request
058 */
059 String getLabel();
060
061 /**
062 * Gets the URL that Latka will attempt to contact. Note:
063 * since Latka will respect most redirects, this may not
064 * be the URL that returns the actual response.
065 *
066 * @return the URL associated with this HTTP request
067 */
068 URL getURL();
069
070 /**
071 * Associate a parameter with this request.
072 *
073 * @param name the name of the parameter
074 * @param value the value of the parameter
075 *
076 */
077 void addParameter(String name, String value);
078
079 /**
080 * Set all the parameters for the request. Overrides
081 * any parameters that have been already set by addParameter();
082 *
083 * @param parameters
084 * all parameters for this request
085 */
086 void setParameters(Parameters parameters);
087
088 /**
089 * Get the parameters for the request, so that they can
090 * be copied to another request if necessary.
091 *
092 * @return parameters for this request
093 */
094 Parameters getParameters();
095
096 /**
097 * Sets a request header.
098 *
099 * @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 }