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
021 /**
022 * A Latka Session is a container that manages state information
023 * over 1+ HTTP request/response pairs over 1+ HTTP servers.
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 * @version $Id: Session.java 155424 2005-02-26 13:09:29Z dirkv $
029 */
030 public interface Session {
031
032 /**
033 * Creates a request object with the specified URL, HTTP Method,
034 * and version.
035 *
036 * @param url The URL to request of the HTTP server.
037 * @param httpMethod An integer representing the HTTP method (e.g. GET, PUT)
038 * used to communicate with server.
039 * @param version A String representing the version of the HTTP request, i.e.
040 * 1.0 or 1.1.
041 * @return a new {@link Request} object representing the <code>url</code>
042 * and <code>httpMethod</code>
043 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_GET
044 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_POST
045 */
046 Request createRequest(URL url, int httpMethod, String version);
047
048 /**
049 * Creates a labeled request object, with the specified URL, HTTP Method,
050 * version, and redirect handling behavior.
051 *
052 * @param label a name used to identify the request
053 * @param url The URL to request of the HTTP server.
054 * @param httpMethod An integer representing the HTTP method (e.g. GET, PUT)
055 * used to communicate with server.
056 * @param version A String representing the version of the HTTP request, i.e.
057 * 1.0 or 1.1.
058 * @param followRedirects whether to follow HTTP redirection responses
059 * @return a new {@link Request} object representing the <code>url</code>
060 * and <code>httpMethod</code>
061 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_GET
062 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_POST
063 */
064 Request createRequest(String label, URL url, int httpMethod,
065 String version, boolean followRedirects);
066
067 /**
068 * Creates a request object with the specified URL, HTTP Method, and
069 * version to be accessed via the provided proxy.
070 *
071 * @param url The URL to request of the HTTP server.
072 * @param httpMethod An integer representing the HTTP method (e.g. GET, PUT)
073 * used to communicate with server.
074 * @param proxy a proxy to use during the request
075 * @param version A String representing the version of the HTTP request, i.e.
076 * 1.0 or 1.1.
077 * @return a new {@link Request} object representing the <code>url</code>
078 * and <code>httpMethod</code>.
079 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_GET
080 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_POST
081 * @see org.apache.commons.latka.http.Proxy
082 */
083 Request createRequest(URL url, int httpMethod, Proxy proxy, String version);
084
085 /**
086 * Create a labeled request with the specified URL, HTTP method, version, and
087 * redirect handling behavior, using the given proxy for communication.
088 *
089 * @param label a name used to identify the request
090 * @param url The URL to request of the HTTP server.
091 * @param httpMethod An integer representing the HTTP method (e.g. GET, PUT)
092 * used to communicate with server.
093 * @param version A String representing the version of the HTTP request, i.e.
094 * 1.0 or 1.1.
095 * @param followRedirects whether to follow HTTP redirection responses
096 * @param proxy a proxy to use during the request
097 * @return a new {@link Request} object representing the <code>url</code>
098 * and <code>httpMethod</code>
099 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_GET
100 * @see org.apache.commons.latka.http.Request#HTTP_METHOD_POST
101 * @see org.apache.commons.latka.http.Proxy
102 */
103 Request createRequest(String label, URL url, int httpMethod,
104 String version, boolean followRedirects, Proxy proxy);
105
106 /**
107 * Adds a cookie to all HTTP requests whose domain and path match
108 * (according to RFC2109).
109 *
110 * @param domain the domain to which the cookie should apply
111 * @param path the path to which the cookie should apply
112 * @param name the name of the cookie
113 * @param value the value of the cookie
114 */
115 void addCookie(String domain, String path,
116 String name, String value);
117
118 /**
119 * Returns the value of cookie <code>name</code>.
120 *
121 * @param name the name of the cookie
122 *
123 * @return the value of the cookie, or null if the cookie isn't set
124 */
125 String getCookieValue(String name);
126
127 }