001: /*
002: * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpec.java,v 1.11 2004/09/14 20:11:31 olegk Exp $
003: * $Revision: 480424 $
004: * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
005: *
006: * ====================================================================
007: *
008: * Licensed to the Apache Software Foundation (ASF) under one or more
009: * contributor license agreements. See the NOTICE file distributed with
010: * this work for additional information regarding copyright ownership.
011: * The ASF licenses this file to You under the Apache License, Version 2.0
012: * (the "License"); you may not use this file except in compliance with
013: * the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing, software
018: * distributed under the License is distributed on an "AS IS" BASIS,
019: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020: * See the License for the specific language governing permissions and
021: * limitations under the License.
022: * ====================================================================
023: *
024: * This software consists of voluntary contributions made by many
025: * individuals on behalf of the Apache Software Foundation. For more
026: * information on the Apache Software Foundation, please see
027: * <http://www.apache.org/>.
028: *
029: */
030:
031: package org.apache.commons.httpclient.cookie;
032:
033: import java.util.Collection;
034:
035: import org.apache.commons.httpclient.Header;
036: import org.apache.commons.httpclient.NameValuePair;
037: import org.apache.commons.httpclient.Cookie;
038:
039: /**
040: * Defines the cookie management specification.
041: * <p>Cookie management specification must define
042: * <ul>
043: * <li> rules of parsing "Set-Cookie" header
044: * <li> rules of validation of parsed cookies
045: * <li> formatting of "Cookie" header
046: * </ul>
047: * for a given host, port and path of origin
048: *
049: * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
050: * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a>
051: *
052: * @since 2.0
053: */
054: public interface CookieSpec {
055:
056: /** Path delimiter */
057: static final String PATH_DELIM = "/";
058:
059: /** Path delimiting charachter */
060: static final char PATH_DELIM_CHAR = PATH_DELIM.charAt(0);
061:
062: /**
063: * Parse the <tt>"Set-Cookie"</tt> header value into Cookie array.
064: *
065: * <p>This method will not perform the validation of the resultant
066: * {@link Cookie}s</p>
067: *
068: * @see #validate(String, int, String, boolean, Cookie)
069: *
070: * @param host the host which sent the <tt>Set-Cookie</tt> header
071: * @param port the port which sent the <tt>Set-Cookie</tt> header
072: * @param path the path which sent the <tt>Set-Cookie</tt> header
073: * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
074: * was received over secure conection
075: * @param header the <tt>Set-Cookie</tt> received from the server
076: * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
077: * @throws MalformedCookieException if an exception occurs during parsing
078: * @throws IllegalArgumentException if an input parameter is illegal
079: */
080: Cookie[] parse(String host, int port, String path, boolean secure,
081: final String header) throws MalformedCookieException,
082: IllegalArgumentException;
083:
084: /**
085: * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
086: *
087: * <p>This method will not perform the validation of the resultant
088: * {@link Cookie}s</p>
089: *
090: * @see #validate(String, int, String, boolean, Cookie)
091: *
092: * @param host the host which sent the <tt>Set-Cookie</tt> header
093: * @param port the port which sent the <tt>Set-Cookie</tt> header
094: * @param path the path which sent the <tt>Set-Cookie</tt> header
095: * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
096: * was received over secure conection
097: * @param header the <tt>Set-Cookie</tt> received from the server
098: * @return an array of <tt>Cookie</tt>s parsed from the header
099: * @throws MalformedCookieException if an exception occurs during parsing
100: * @throws IllegalArgumentException if an input parameter is illegal
101: */
102: Cookie[] parse(String host, int port, String path, boolean secure,
103: final Header header) throws MalformedCookieException,
104: IllegalArgumentException;
105:
106: /**
107: * Parse the cookie attribute and update the corresponsing Cookie
108: * properties.
109: *
110: * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
111: * @param cookie the to be updated
112: * @throws MalformedCookieException if an exception occurs during parsing
113: * @throws IllegalArgumentException if an input parameter is illegal
114: */
115: void parseAttribute(NameValuePair attribute, Cookie cookie)
116: throws MalformedCookieException, IllegalArgumentException;
117:
118: /**
119: * Validate the cookie according to validation rules defined by the
120: * cookie specification.
121: *
122: * @param host the host from which the {@link Cookie} was received
123: * @param port the port from which the {@link Cookie} was received
124: * @param path the path from which the {@link Cookie} was received
125: * @param secure <tt>true</tt> when the {@link Cookie} was received
126: * using a secure connection
127: * @param cookie the Cookie to validate
128: * @throws MalformedCookieException if the cookie is invalid
129: * @throws IllegalArgumentException if an input parameter is illegal
130: */
131: void validate(String host, int port, String path, boolean secure,
132: final Cookie cookie) throws MalformedCookieException,
133: IllegalArgumentException;
134:
135: /**
136: * Sets the {@link Collection} of date patterns used for parsing. The String patterns must be
137: * compatible with {@link java.text.SimpleDateFormat}.
138: *
139: * @param datepatterns collection of date patterns
140: */
141: void setValidDateFormats(Collection datepatterns);
142:
143: /**
144: * Returns the {@link Collection} of date patterns used for parsing. The String patterns are compatible
145: * with the {@link java.text.SimpleDateFormat}.
146: *
147: * @return collection of date patterns
148: */
149: Collection getValidDateFormats();
150:
151: /**
152: * Determines if a Cookie matches a location.
153: *
154: * @param host the host to which the request is being submitted
155: * @param port the port to which the request is being submitted
156: * @param path the path to which the request is being submitted
157: * @param secure <tt>true</tt> if the request is using a secure connection
158: * @param cookie the Cookie to be matched
159: *
160: * @return <tt>true</tt> if the cookie should be submitted with a request
161: * with given attributes, <tt>false</tt> otherwise.
162: */
163: boolean match(String host, int port, String path, boolean secure,
164: final Cookie cookie);
165:
166: /**
167: * Determines which of an array of Cookies matches a location.
168: *
169: * @param host the host to which the request is being submitted
170: * @param port the port to which the request is being submitted
171: * (currenlty ignored)
172: * @param path the path to which the request is being submitted
173: * @param secure <tt>true</tt> if the request is using a secure protocol
174: * @param cookies an array of <tt>Cookie</tt>s to be matched
175: *
176: * @return <tt>true</tt> if the cookie should be submitted with a request
177: * with given attributes, <tt>false</tt> otherwise.
178: */
179: Cookie[] match(String host, int port, String path, boolean secure,
180: final Cookie cookies[]);
181:
182: /**
183: * Performs domain-match as defined by the cookie specification.
184: * @param host The target host.
185: * @param domain The cookie domain attribute.
186: * @return true if the specified host matches the given domain.
187: *
188: * @since 3.0
189: */
190: boolean domainMatch(String host, String domain);
191:
192: /**
193: * Performs path-match as defined by the cookie specification.
194: * @param path The target path.
195: * @param topmostPath The cookie path attribute.
196: * @return true if the paths match
197: *
198: * @since 3.0
199: */
200: boolean pathMatch(String path, String topmostPath);
201:
202: /**
203: * Create a <tt>"Cookie"</tt> header value for an array of cookies.
204: *
205: * @param cookie the cookie to be formatted as string
206: * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
207: */
208: String formatCookie(Cookie cookie);
209:
210: /**
211: * Create a <tt>"Cookie"</tt> header value for an array of cookies.
212: *
213: * @param cookies the Cookies to be formatted
214: * @return a string suitable for sending in a Cookie header.
215: * @throws IllegalArgumentException if an input parameter is illegal
216: */
217: String formatCookies(Cookie[] cookies)
218: throws IllegalArgumentException;
219:
220: /**
221: * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
222: *
223: * @param cookies the Cookies format into a Cookie header
224: * @return a Header for the given Cookies.
225: * @throws IllegalArgumentException if an input parameter is illegal
226: */
227: Header formatCookieHeader(Cookie[] cookies)
228: throws IllegalArgumentException;
229:
230: /**
231: * Create a <tt>"Cookie"</tt> Header for single Cookie.
232: *
233: * @param cookie the Cookie format as a <tt>Cookie</tt> header
234: * @return a Cookie header.
235: * @throws IllegalArgumentException if an input parameter is illegal
236: */
237: Header formatCookieHeader(Cookie cookie)
238: throws IllegalArgumentException;
239:
240: }
|