Request


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 }
196
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags