001: /*
002: * $Header$
003: * $Revision: 3526 $
004: * $Date: 2005-06-06 17:50:03 +0000 (Mon, 06 Jun 2005) $
005: *
006: * ====================================================================
007: *
008: * Copyright 2002-2004 The Apache Software Foundation
009: *
010: * Licensed under the Apache License, Version 2.0 (the "License");
011: * you may not use this file except in compliance with the License.
012: * You may obtain a copy of the License at
013: *
014: * http://www.apache.org/licenses/LICENSE-2.0
015: *
016: * Unless required by applicable law or agreed to in writing, software
017: * distributed under the License is distributed on an "AS IS" BASIS,
018: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
019: * See the License for the specific language governing permissions and
020: * limitations under the License.
021: * ====================================================================
022: *
023: * This software consists of voluntary contributions made by many
024: * individuals on behalf of the Apache Software Foundation. For more
025: * information on the Apache Software Foundation, please see
026: * <http://www.apache.org/>.
027: *
028: */
029:
030: package org.apache.commons.httpclient.cookie;
031:
032: import java.util.Collection;
033: import java.util.SortedMap;
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: * @param host the host which sent the <tt>Set-Cookie</tt> header
066: * @param port the port which sent the <tt>Set-Cookie</tt> header
067: * @param path the path which sent the <tt>Set-Cookie</tt> header
068: * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
069: * was received over secure conection
070: * @param header the <tt>Set-Cookie</tt> received from the server
071: * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
072: * @throws MalformedCookieException if an exception occurs during parsing
073: * @throws IllegalArgumentException if an input parameter is illegal
074: */
075: Cookie[] parse(String host, int port, String path, boolean secure,
076: final String header) throws MalformedCookieException,
077: IllegalArgumentException;
078:
079: /**
080: * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
081: *
082: * @param host the host which sent the <tt>Set-Cookie</tt> header
083: * @param port the port which sent the <tt>Set-Cookie</tt> header
084: * @param path the path which sent the <tt>Set-Cookie</tt> header
085: * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
086: * was received over secure conection
087: * @param header the <tt>Set-Cookie</tt> received from the server
088: * @return an array of <tt>Cookie</tt>s parsed from the header
089: * @throws MalformedCookieException if an exception occurs during parsing
090: * @throws IllegalArgumentException if an input parameter is illegal
091: */
092: Cookie[] parse(String host, int port, String path, boolean secure,
093: final Header header) throws MalformedCookieException,
094: IllegalArgumentException;
095:
096: /**
097: * Parse the cookie attribute and update the corresponsing Cookie
098: * properties.
099: *
100: * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
101: * @param cookie the to be updated
102: * @throws MalformedCookieException if an exception occurs during parsing
103: * @throws IllegalArgumentException if an input parameter is illegal
104: */
105: void parseAttribute(NameValuePair attribute, Cookie cookie)
106: throws MalformedCookieException, IllegalArgumentException;
107:
108: /**
109: * Validate the cookie according to validation rules defined by the
110: * cookie specification.
111: *
112: * @param host the host from which the {@link Cookie} was received
113: * @param port the port from which the {@link Cookie} was received
114: * @param path the path from which the {@link Cookie} was received
115: * @param secure <tt>true</tt> when the {@link Cookie} was received
116: * using a secure connection
117: * @param cookie the Cookie to validate
118: * @throws MalformedCookieException if the cookie is invalid
119: * @throws IllegalArgumentException if an input parameter is illegal
120: */
121: void validate(String host, int port, String path, boolean secure,
122: final Cookie cookie) throws MalformedCookieException,
123: IllegalArgumentException;
124:
125: /**
126: * Sets the {@link Collection} of date patterns used for parsing. The String patterns must be
127: * compatible with {@link java.text.SimpleDateFormat}.
128: *
129: * @param datepatterns collection of date patterns
130: */
131: void setValidDateFormats(Collection datepatterns);
132:
133: /**
134: * Returns the {@link Collection} of date patterns used for parsing. The String patterns are compatible
135: * with the {@link java.text.SimpleDateFormat}.
136: *
137: * @return collection of date patterns
138: */
139: Collection getValidDateFormats();
140:
141: /**
142: * Determines if a Cookie matches a location.
143: *
144: * @param host the host to which the request is being submitted
145: * @param port the port to which the request is being submitted
146: * @param path the path to which the request is being submitted
147: * @param secure <tt>true</tt> if the request is using a secure connection
148: * @param cookie the Cookie to be matched
149: *
150: * @return <tt>true</tt> if the cookie should be submitted with a request
151: * with given attributes, <tt>false</tt> otherwise.
152: */
153: boolean match(String host, int port, String path, boolean secure,
154: final Cookie cookie);
155:
156: /**
157: * Determines which of an array of Cookies matches a location.
158: *
159: * @param host the host to which the request is being submitted
160: * @param port the port to which the request is being submitted
161: * (currenlty ignored)
162: * @param path the path to which the request is being submitted
163: * @param secure <tt>true</tt> if the request is using a secure protocol
164: * @param cookies an array of <tt>Cookie</tt>s to be matched
165: *
166: * @return <tt>true</tt> if the cookie should be submitted with a request
167: * with given attributes, <tt>false</tt> otherwise.
168: *
169: // BEGIN IA CHANGES
170: * @deprecated use match(String, int, String, boolean, SortedMap)
171: // END IA CHANGES
172: */
173: Cookie[] match(String host, int port, String path, boolean secure,
174: final Cookie cookies[]);
175:
176: // BEGIN IA CHANGES
177: /**
178: * Determines which of an array of Cookies matches a location.
179: *
180: * If the SortedMap comes from an HttpState and is not itself
181: * thread-safe, it may be necessary to synchronize on the HttpState
182: * instance to protect against concurrent modification.
183: *
184: * @param host the host to which the request is being submitted
185: * @param port the port to which the request is being submitted
186: * (currenlty ignored)
187: * @param path the path to which the request is being submitted
188: * @param secure <tt>true</tt> if the request is using a secure protocol
189: * @param cookies SortedMap of <tt>Cookie</tt>s to be matched
190: *
191: * @return <tt>true</tt> if the cookie should be submitted with a request
192: * with given attributes, <tt>false</tt> otherwise.
193: */
194: Cookie[] match(String domain, int port, String path,
195: boolean secure, SortedMap cookiesMap);
196:
197: // END IA CHANGES
198:
199: /**
200: * Performs domain-match as defined by the cookie specification.
201: * @param host The target host.
202: * @param domain The cookie domain attribute.
203: * @return true if the specified host matches the given domain.
204: *
205: * @since 3.0
206: */
207: boolean domainMatch(String host, String domain);
208:
209: /**
210: * Performs path-match as defined by the cookie specification.
211: * @param path The target path.
212: * @param topmostPath The cookie path attribute.
213: * @return true if the paths match
214: *
215: * @since 3.0
216: */
217: boolean pathMatch(String path, String topmostPath);
218:
219: /**
220: * Create a <tt>"Cookie"</tt> header value for an array of cookies.
221: *
222: * @param cookie the cookie to be formatted as string
223: * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
224: */
225: String formatCookie(Cookie cookie);
226:
227: /**
228: * Create a <tt>"Cookie"</tt> header value for an array of cookies.
229: *
230: * @param cookies the Cookies to be formatted
231: * @return a string suitable for sending in a Cookie header.
232: * @throws IllegalArgumentException if an input parameter is illegal
233: */
234: String formatCookies(Cookie[] cookies)
235: throws IllegalArgumentException;
236:
237: /**
238: * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
239: *
240: * @param cookies the Cookies format into a Cookie header
241: * @return a Header for the given Cookies.
242: * @throws IllegalArgumentException if an input parameter is illegal
243: */
244: Header formatCookieHeader(Cookie[] cookies)
245: throws IllegalArgumentException;
246:
247: /**
248: * Create a <tt>"Cookie"</tt> Header for single Cookie.
249: *
250: * @param cookie the Cookie format as a <tt>Cookie</tt> header
251: * @return a Cookie header.
252: * @throws IllegalArgumentException if an input parameter is illegal
253: */
254: Header formatCookieHeader(Cookie cookie)
255: throws IllegalArgumentException;
256:
257: }
|