KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > httpclient > cookie > CookieSpec


1 /*
2  * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpec.java,v 1.6.2.2 2004/02/22 18:21:15 olegk Exp $
3  * $Revision: 1.6.2.2 $
4  * $Date: 2004/02/22 18:21:15 $
5  *
6  * ====================================================================
7  *
8  * Copyright 2002-2004 The Apache Software Foundation
9  *
10  * Licensed under the Apache License, Version 2.0 (the "License");
11  * you may not use this file except in compliance with the License.
12  * You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing, software
17  * distributed under the License is distributed on an "AS IS" BASIS,
18  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19  * See the License for the specific language governing permissions and
20  * limitations under the License.
21  * ====================================================================
22  *
23  * This software consists of voluntary contributions made by many
24  * individuals on behalf of the Apache Software Foundation. For more
25  * information on the Apache Software Foundation, please see
26  * <http://www.apache.org/>.
27  *
28  * [Additional notices, if required by prior licensing conditions]
29  *
30  */
31
32 package org.apache.commons.httpclient.cookie;
33
34 import org.apache.commons.httpclient.Header;
35 import org.apache.commons.httpclient.NameValuePair;
36 import org.apache.commons.httpclient.Cookie;
37
38 /**
39  * Defines the cookie management specification.
40  * <p>Cookie management specification must define
41  * <ul>
42  * <li> rules of parsing "Set-Cookie" header
43  * <li> rules of validation of parsed cookies
44  * <li> formatting of "Cookie" header
45  * </ul>
46  * for a given host, port and path of origin
47  *
48  * @author <a HREF="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
49  * @author <a HREF="mailto:jsdever@apache.org">Jeff Dever</a>
50  *
51  * @since 2.0
52  */
53 public interface CookieSpec {
54
55     /** Path delimiter */
56     String JavaDoc PATH_DELIM = "/";
57
58     /** Path delimiting charachter */
59     char PATH_DELIM_CHAR = PATH_DELIM.charAt(0);
60
61     /**
62       * Parse the <tt>"Set-Cookie"</tt> header value into Cookie array.
63       *
64       * @param host the host which sent the <tt>Set-Cookie</tt> header
65       * @param port the port which sent the <tt>Set-Cookie</tt> header
66       * @param path the path which sent the <tt>Set-Cookie</tt> header
67       * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
68       * was received over secure conection
69       * @param header the <tt>Set-Cookie</tt> received from the server
70       * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
71       * @throws MalformedCookieException if an exception occurs during parsing
72       * @throws IllegalArgumentException if an input parameter is illegal
73       */
74     Cookie[] parse(String JavaDoc host, int port, String JavaDoc path, boolean secure,
75       final String JavaDoc header)
76       throws MalformedCookieException, IllegalArgumentException JavaDoc;
77
78     /**
79       * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
80       *
81       * @param host the host which sent the <tt>Set-Cookie</tt> header
82       * @param port the port which sent the <tt>Set-Cookie</tt> header
83       * @param path the path which sent the <tt>Set-Cookie</tt> header
84       * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
85       * was received over secure conection
86       * @param header the <tt>Set-Cookie</tt> received from the server
87       * @return an array of <tt>Cookie</tt>s parsed from the header
88       * @throws MalformedCookieException if an exception occurs during parsing
89       * @throws IllegalArgumentException if an input parameter is illegal
90       */
91     Cookie[] parse(String JavaDoc host, int port, String JavaDoc path, boolean secure,
92       final Header header)
93       throws MalformedCookieException, IllegalArgumentException JavaDoc;
94
95     /**
96       * Parse the cookie attribute and update the corresponsing Cookie
97       * properties.
98       *
99       * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
100       * @param cookie the to be updated
101       * @throws MalformedCookieException if an exception occurs during parsing
102       * @throws IllegalArgumentException if an input parameter is illegal
103       */
104     void parseAttribute(final NameValuePair attribute, final Cookie cookie)
105       throws MalformedCookieException, IllegalArgumentException JavaDoc;
106
107     /**
108       * Validate the cookie according to validation rules defined by the
109       * cookie specification.
110       *
111       * @param host the host from which the {@link Cookie} was received
112       * @param port the port from which the {@link Cookie} was received
113       * @param path the path from which the {@link Cookie} was received
114       * @param secure <tt>true</tt> when the {@link Cookie} was received
115       * using a secure connection
116       * @param cookie the Cookie to validate
117       * @throws MalformedCookieException if the cookie is invalid
118       * @throws IllegalArgumentException if an input parameter is illegal
119       */
120     void validate(String JavaDoc host, int port, String JavaDoc path, boolean secure,
121       final Cookie cookie)
122       throws MalformedCookieException, IllegalArgumentException JavaDoc;
123     
124     /**
125      * Determines if a Cookie matches a location.
126      *
127      * @param host the host to which the request is being submitted
128      * @param port the port to which the request is being submitted
129      * @param path the path to which the request is being submitted
130      * @param secure <tt>true</tt> if the request is using a secure connection
131      * @param cookie the Cookie to be matched
132      *
133      * @return <tt>true</tt> if the cookie should be submitted with a request
134      * with given attributes, <tt>false</tt> otherwise.
135      */
136     boolean match(String JavaDoc host, int port, String JavaDoc path, boolean secure,
137         final Cookie cookie);
138
139     /**
140      * Determines which of an array of Cookies matches a location.
141      *
142      * @param host the host to which the request is being submitted
143      * @param port the port to which the request is being submitted
144      * (currenlty ignored)
145      * @param path the path to which the request is being submitted
146      * @param secure <tt>true</tt> if the request is using a secure protocol
147      * @param cookies an array of <tt>Cookie</tt>s to be matched
148      *
149      * @return <tt>true</tt> if the cookie should be submitted with a request
150      * with given attributes, <tt>false</tt> otherwise.
151      */
152     Cookie[] match(String JavaDoc host, int port, String JavaDoc path, boolean secure,
153         final Cookie cookies[]);
154
155     /**
156      * Create a <tt>"Cookie"</tt> header value for an array of cookies.
157      *
158      * @param cookie the cookie to be formatted as string
159      * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
160      */
161     String JavaDoc formatCookie(Cookie cookie);
162
163     /**
164      * Create a <tt>"Cookie"</tt> header value for an array of cookies.
165      *
166      * @param cookies the Cookies to be formatted
167      * @return a string suitable for sending in a Cookie header.
168      * @throws IllegalArgumentException if an input parameter is illegal
169      */
170     String JavaDoc formatCookies(Cookie[] cookies) throws IllegalArgumentException JavaDoc;
171     
172     /**
173      * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
174      *
175      * @param cookies the Cookies format into a Cookie header
176      * @return a Header for the given Cookies.
177      * @throws IllegalArgumentException if an input parameter is illegal
178      */
179     Header formatCookieHeader(Cookie[] cookies) throws IllegalArgumentException JavaDoc;
180
181     /**
182      * Create a <tt>"Cookie"</tt> Header for single Cookie.
183      *
184      * @param cookie the Cookie format as a <tt>Cookie</tt> header
185      * @return a Cookie header.
186      * @throws IllegalArgumentException if an input parameter is illegal
187      */
188     Header formatCookieHeader(Cookie cookie) throws IllegalArgumentException JavaDoc;
189
190 }
191
Popular Tags