diff options
Diffstat (limited to 'src/org/apache/http/cookie')
17 files changed, 1367 insertions, 0 deletions
diff --git a/src/org/apache/http/cookie/ClientCookie.java b/src/org/apache/http/cookie/ClientCookie.java new file mode 100644 index 0000000..96edec9 --- /dev/null +++ b/src/org/apache/http/cookie/ClientCookie.java @@ -0,0 +1,67 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/ClientCookie.java $ + * $Revision: 578403 $ + * $Date: 2007-09-22 03:56:04 -0700 (Sat, 22 Sep 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +/** + * ClientCookie extends the standard {@link Cookie} interface with + * additional client specific functionality such ability to retrieve + * original cookie attributes exactly as they were specified by the + * origin server. This is important for generating the <tt>Cookie</tt> + * header because some cookie specifications require that the + * <tt>Cookie</tt> header should include certain attributes only if + * they were specified in the <tt>Set-Cookie</tt> header. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public interface ClientCookie extends Cookie { + + // RFC2109 attributes + public static final String VERSION_ATTR = "version"; + public static final String PATH_ATTR = "path"; + public static final String DOMAIN_ATTR = "domain"; + public static final String MAX_AGE_ATTR = "max-age"; + public static final String SECURE_ATTR = "secure"; + public static final String COMMENT_ATTR = "comment"; + public static final String EXPIRES_ATTR = "expires"; + + // RFC2965 attributes + public static final String PORT_ATTR = "port"; + public static final String COMMENTURL_ATTR = "commenturl"; + public static final String DISCARD_ATTR = "discard"; + + String getAttribute(String name); + + boolean containsAttribute(String name); + +}
\ No newline at end of file diff --git a/src/org/apache/http/cookie/Cookie.java b/src/org/apache/http/cookie/Cookie.java new file mode 100644 index 0000000..5eae9d5 --- /dev/null +++ b/src/org/apache/http/cookie/Cookie.java @@ -0,0 +1,139 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/Cookie.java $ + * $Revision: 578403 $ + * $Date: 2007-09-22 03:56:04 -0700 (Sat, 22 Sep 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import java.util.Date; + +/** + * HTTP "magic-cookie" represents a piece of state information + * that the HTTP agent and the target server can exchange to maintain + * a session. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public interface Cookie { + + /** + * Returns the name. + * + * @return String name The name + */ + String getName(); + + /** + * Returns the value. + * + * @return String value The current value. + */ + String getValue(); + + /** + * Returns the comment describing the purpose of this cookie, or + * <tt>null</tt> if no such comment has been defined. + * + * @return comment + */ + String getComment(); + + /** + * If a user agent (web browser) presents this cookie to a user, the + * cookie's purpose will be described by the information at this URL. + */ + String getCommentURL(); + + /** + * Returns the expiration {@link Date} of the cookie, or <tt>null</tt> + * if none exists. + * <p><strong>Note:</strong> the object returned by this method is + * considered immutable. Changing it (e.g. using setTime()) could result + * in undefined behaviour. Do so at your peril. </p> + * @return Expiration {@link Date}, or <tt>null</tt>. + */ + Date getExpiryDate(); + + /** + * Returns <tt>false</tt> if the cookie should be discarded at the end + * of the "session"; <tt>true</tt> otherwise. + * + * @return <tt>false</tt> if the cookie should be discarded at the end + * of the "session"; <tt>true</tt> otherwise + */ + boolean isPersistent(); + + /** + * Returns domain attribute of the cookie. + * + * @return the value of the domain attribute + */ + String getDomain(); + + /** + * Returns the path attribute of the cookie + * + * @return The value of the path attribute. + */ + String getPath(); + + /** + * Get the Port attribute. It restricts the ports to which a cookie + * may be returned in a Cookie request header. + */ + int[] getPorts(); + + /** + * Indicates whether this cookie requires a secure connection. + * + * @return <code>true</code> if this cookie should only be sent + * over secure connections, <code>false</code> otherwise. + */ + boolean isSecure(); + + /** + * Returns the version of the cookie specification to which this + * cookie conforms. + * + * @return the version of the cookie. + */ + int getVersion(); + + /** + * Returns true if this cookie has expired. + * @param date Current time + * + * @return <tt>true</tt> if the cookie has expired. + */ + boolean isExpired(final Date date); + +} + diff --git a/src/org/apache/http/cookie/CookieAttributeHandler.java b/src/org/apache/http/cookie/CookieAttributeHandler.java new file mode 100644 index 0000000..a79d115 --- /dev/null +++ b/src/org/apache/http/cookie/CookieAttributeHandler.java @@ -0,0 +1,78 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/CookieAttributeHandler.java $ + * $Revision: 558519 $ + * $Date: 2007-07-22 11:19:49 -0700 (Sun, 22 Jul 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ +package org.apache.http.cookie; + +/** + * Ths interface represents a cookie attribute handler responsible + * for parsing, validating, and matching a specific cookie attribute, + * such as path, domain, port, etc. + * + * Different cookie specifications can provide a specific + * implementation for this class based on their cookie handling + * rules. + * + * @author jain.samit@gmail.com (Samit Jain) + * + * @since 4.0 + */ +public interface CookieAttributeHandler { + + /** + * Parse the given cookie attribute value and update the corresponding + * {@link org.apache.http.cookie.Cookie} property. + * + * @param cookie {@link org.apache.http.cookie.Cookie} to be updated + * @param value cookie attribute value from the cookie response header + */ + void parse(SetCookie cookie, String value) + throws MalformedCookieException; + + /** + * Peforms cookie validation for the given attribute value. + * + * @param cookie {@link org.apache.http.cookie.Cookie} to validate + * @param origin the cookie source to validate against + * @throws MalformedCookieException if cookie validation fails for this attribute + */ + void validate(Cookie cookie, CookieOrigin origin) + throws MalformedCookieException; + + /** + * Matches the given value (property of the destination host where request is being + * submitted) with the corresponding cookie attribute. + * + * @param cookie {@link org.apache.http.cookie.Cookie} to match + * @param origin the cookie source to match against + * @return <tt>true</tt> if the match is successful; <tt>false</tt> otherwise + */ + boolean match(Cookie cookie, CookieOrigin origin); + +} diff --git a/src/org/apache/http/cookie/CookieIdentityComparator.java b/src/org/apache/http/cookie/CookieIdentityComparator.java new file mode 100644 index 0000000..4fc701c --- /dev/null +++ b/src/org/apache/http/cookie/CookieIdentityComparator.java @@ -0,0 +1,68 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/CookieIdentityComparator.java $ + * $Revision: 618308 $ + * $Date: 2008-02-04 07:51:19 -0800 (Mon, 04 Feb 2008) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import java.io.Serializable; +import java.util.Comparator; + +/** + * This cookie comparator can be used to compare identity of cookies. + * + * <p> + * Cookies are considered identical if their names are equal and + * their domain attributes match ignoring case. + * </p> + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + */ +public class CookieIdentityComparator implements Serializable, Comparator<Cookie> { + + private static final long serialVersionUID = 4466565437490631532L; + + public int compare(final Cookie c1, final Cookie c2) { + int res = c1.getName().compareTo(c2.getName()); + if (res == 0) { + // do not differentiate empty and null domains + String d1 = c1.getDomain(); + if (d1 == null) { + d1 = ""; + } + String d2 = c2.getDomain(); + if (d2 == null) { + d2 = ""; + } + res = d1.compareToIgnoreCase(d2); + } + return res; + } + +} diff --git a/src/org/apache/http/cookie/CookieOrigin.java b/src/org/apache/http/cookie/CookieOrigin.java new file mode 100644 index 0000000..ad0448a --- /dev/null +++ b/src/org/apache/http/cookie/CookieOrigin.java @@ -0,0 +1,108 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/CookieOrigin.java $ + * $Revision: 653041 $ + * $Date: 2008-05-03 03:39:28 -0700 (Sat, 03 May 2008) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ +package org.apache.http.cookie; + +import java.util.Locale; + +/** + * CookieOrigin class incapsulates details of an origin server that + * are relevant when parsing, validating or matching HTTP cookies. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public final class CookieOrigin { + + private final String host; + private final int port; + private final String path; + private final boolean secure; + + public CookieOrigin(final String host, int port, final String path, boolean secure) { + super(); + if (host == null) { + throw new IllegalArgumentException( + "Host of origin may not be null"); + } + if (host.trim().length() == 0) { + throw new IllegalArgumentException( + "Host of origin may not be blank"); + } + if (port < 0) { + throw new IllegalArgumentException("Invalid port: " + port); + } + if (path == null) { + throw new IllegalArgumentException( + "Path of origin may not be null."); + } + this.host = host.toLowerCase(Locale.ENGLISH); + this.port = port; + if (path.trim().length() != 0) { + this.path = path; + } else { + this.path = "/"; + } + this.secure = secure; + } + + public String getHost() { + return this.host; + } + + public String getPath() { + return this.path; + } + + public int getPort() { + return this.port; + } + + public boolean isSecure() { + return this.secure; + } + + @Override + public String toString() { + StringBuilder buffer = new StringBuilder(); + buffer.append('['); + if (this.secure) { + buffer.append("(secure)"); + } + buffer.append(this.host); + buffer.append(':'); + buffer.append(Integer.toString(this.port)); + buffer.append(this.path); + buffer.append(']'); + return buffer.toString(); + } + +} diff --git a/src/org/apache/http/cookie/CookiePathComparator.java b/src/org/apache/http/cookie/CookiePathComparator.java new file mode 100644 index 0000000..f5f0a66 --- /dev/null +++ b/src/org/apache/http/cookie/CookiePathComparator.java @@ -0,0 +1,81 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/CookiePathComparator.java $ + * $Revision: 653041 $ + * $Date: 2008-05-03 03:39:28 -0700 (Sat, 03 May 2008) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import java.io.Serializable; +import java.util.Comparator; + +/** + * This cookie comparator ensures that multiple cookies satisfying + * a common criteria are ordered in the <tt>Cookie</tt> header such + * that those with more specific Path attributes precede those with + * less specific. + * + * <p> + * This comparator assumes that Path attributes of two cookies + * path-match a commmon request-URI. Otherwise, the result of the + * comparison is undefined. + * </p> + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + */ +public class CookiePathComparator implements Serializable, Comparator<Cookie> { + + private static final long serialVersionUID = 7523645369616405818L; + + private String normalizePath(final Cookie cookie) { + String path = cookie.getPath(); + if (path == null) { + path = "/"; + } + if (!path.endsWith("/")) { + path = path + '/'; + } + return path; + } + + public int compare(final Cookie c1, final Cookie c2) { + String path1 = normalizePath(c1); + String path2 = normalizePath(c2); + if (path1.equals(path2)) { + return 0; + } else if (path1.startsWith(path2)) { + return -1; + } else if (path2.startsWith(path1)) { + return 1; + } else { + // Does not really matter + return 0; + } + } + +} diff --git a/src/org/apache/http/cookie/CookieSpec.java b/src/org/apache/http/cookie/CookieSpec.java new file mode 100644 index 0000000..1eb9f26 --- /dev/null +++ b/src/org/apache/http/cookie/CookieSpec.java @@ -0,0 +1,115 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/CookieSpec.java $ + * $Revision: 603563 $ + * $Date: 2007-12-12 03:17:55 -0800 (Wed, 12 Dec 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import java.util.List; + +import org.apache.http.Header; + +/** + * Defines the cookie management specification. + * <p>Cookie management specification must define + * <ul> + * <li> rules of parsing "Set-Cookie" header + * <li> rules of validation of parsed cookies + * <li> formatting of "Cookie" header + * </ul> + * for a given host, port and path of origin + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a> + * + * @since 4.0 + */ +public interface CookieSpec { + + /** + * Returns version of the state management this cookie specification + * conforms to. + * + * @return version of the state management specification + */ + int getVersion(); + + /** + * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies. + * + * <p>This method will not perform the validation of the resultant + * {@link Cookie}s</p> + * + * @see #validate + * + * @param header the <tt>Set-Cookie</tt> received from the server + * @param origin details of the cookie origin + * @return an array of <tt>Cookie</tt>s parsed from the header + * @throws MalformedCookieException if an exception occurs during parsing + */ + List<Cookie> parse(Header header, CookieOrigin origin) throws MalformedCookieException; + + /** + * Validate the cookie according to validation rules defined by the + * cookie specification. + * + * @param cookie the Cookie to validate + * @param origin details of the cookie origin + * @throws MalformedCookieException if the cookie is invalid + */ + void validate(Cookie cookie, CookieOrigin origin) throws MalformedCookieException; + + /** + * Determines if a Cookie matches the target location. + * + * @param cookie the Cookie to be matched + * @param origin the target to test against + * + * @return <tt>true</tt> if the cookie should be submitted with a request + * with given attributes, <tt>false</tt> otherwise. + */ + boolean match(Cookie cookie, CookieOrigin origin); + + /** + * Create <tt>"Cookie"</tt> headers for an array of Cookies. + * + * @param cookies the Cookies format into a Cookie header + * @return a Header for the given Cookies. + * @throws IllegalArgumentException if an input parameter is illegal + */ + List<Header> formatCookies(List<Cookie> cookies); + + /** + * Returns a request header identifying what version of the state management + * specification is understood. May be <code>null</code> if the cookie + * specification does not support <tt>Cookie2</tt> header. + */ + Header getVersionHeader(); + +} diff --git a/src/org/apache/http/cookie/CookieSpecFactory.java b/src/org/apache/http/cookie/CookieSpecFactory.java new file mode 100644 index 0000000..9d5c21d --- /dev/null +++ b/src/org/apache/http/cookie/CookieSpecFactory.java @@ -0,0 +1,46 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/CookieSpecFactory.java $ + * $Revision: 489636 $ + * $Date: 2006-12-22 04:34:57 -0800 (Fri, 22 Dec 2006) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import org.apache.http.params.HttpParams; + +/** + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public interface CookieSpecFactory { + + CookieSpec newInstance(HttpParams params); + +} diff --git a/src/org/apache/http/cookie/CookieSpecRegistry.java b/src/org/apache/http/cookie/CookieSpecRegistry.java new file mode 100644 index 0000000..64b9c8b --- /dev/null +++ b/src/org/apache/http/cookie/CookieSpecRegistry.java @@ -0,0 +1,160 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/CookieSpecRegistry.java $ + * $Revision: 652950 $ + * $Date: 2008-05-02 16:49:48 -0700 (Fri, 02 May 2008) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Locale; +import java.util.Map; + +import org.apache.http.params.HttpParams; + +/** + * Cookie specification registry that can be used to obtain the corresponding + * cookie specification implementation for a given type of type or version of + * cookie. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a> + * + * @since 4.0 + */ +public final class CookieSpecRegistry { + + private final Map<String,CookieSpecFactory> registeredSpecs; + + public CookieSpecRegistry() { + super(); + this.registeredSpecs = new LinkedHashMap<String,CookieSpecFactory>(); + } + + /** + * Registers a {@link CookieSpecFactory} with the given identifier. + * If a specification with the given name already exists it will be overridden. + * This nameis the same one used to retrieve the {@link CookieSpecFactory} + * from {@link #getCookieSpec(String)}. + * + * @param name the identifier for this specification + * @param factory the {@link CookieSpecFactory} class to register + * + * @see #getCookieSpec(String) + */ + public synchronized void register(final String name, final CookieSpecFactory factory) { + if (name == null) { + throw new IllegalArgumentException("Name may not be null"); + } + if (factory == null) { + throw new IllegalArgumentException("Cookie spec factory may not be null"); + } + registeredSpecs.put(name.toLowerCase(Locale.ENGLISH), factory); + } + + /** + * Unregisters the {@link CookieSpecFactory} with the given ID. + * + * @param id the identifier of the {@link CookieSpec cookie specification} to unregister + */ + public synchronized void unregister(final String id) { + if (id == null) { + throw new IllegalArgumentException("Id may not be null"); + } + registeredSpecs.remove(id.toLowerCase(Locale.ENGLISH)); + } + + /** + * Gets the {@link CookieSpec cookie specification} with the given ID. + * + * @param name the {@link CookieSpec cookie specification} identifier + * @param params the {@link HttpParams HTTP parameters} for the cookie + * specification. + * + * @return {@link CookieSpec cookie specification} + * + * @throws IllegalStateException if a policy with the given name cannot be found + */ + public synchronized CookieSpec getCookieSpec(final String name, final HttpParams params) + throws IllegalStateException { + + if (name == null) { + throw new IllegalArgumentException("Name may not be null"); + } + CookieSpecFactory factory = registeredSpecs.get(name.toLowerCase(Locale.ENGLISH)); + if (factory != null) { + return factory.newInstance(params); + } else { + throw new IllegalStateException("Unsupported cookie spec: " + name); + } + } + + /** + * Gets the {@link CookieSpec cookie specification} with the given name. + * + * @param name the {@link CookieSpec cookie specification} identifier + * + * @return {@link CookieSpec cookie specification} + * + * @throws IllegalStateException if a policy with the given name cannot be found + */ + public synchronized CookieSpec getCookieSpec(final String name) + throws IllegalStateException { + return getCookieSpec(name, null); + } + + /** + * Obtains a list containing names of all registered {@link CookieSpec cookie + * specs} in their default order. + * + * Note that the DEFAULT policy (if present) is likely to be the same + * as one of the other policies, but does not have to be. + * + * @return list of registered cookie spec names + */ + public synchronized List<String> getSpecNames(){ + return new ArrayList<String>(registeredSpecs.keySet()); + } + + /** + * Populates the internal collection of registered {@link CookieSpec cookie + * specs} with the content of the map passed as a parameter. + * + * @param map cookie specs + */ + public synchronized void setItems(final Map<String, CookieSpecFactory> map) { + if (map == null) { + return; + } + registeredSpecs.clear(); + registeredSpecs.putAll(map); + } + +} diff --git a/src/org/apache/http/cookie/MalformedCookieException.java b/src/org/apache/http/cookie/MalformedCookieException.java new file mode 100644 index 0000000..e3f30a9 --- /dev/null +++ b/src/org/apache/http/cookie/MalformedCookieException.java @@ -0,0 +1,74 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/MalformedCookieException.java $ + * $Revision: 508891 $ + * $Date: 2007-02-18 02:08:48 -0800 (Sun, 18 Feb 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import org.apache.http.ProtocolException; + +/** + * Signals that a cookie is in some way invalid or illegal in a given + * context + * + * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public class MalformedCookieException extends ProtocolException { + + private static final long serialVersionUID = -6695462944287282185L; + + /** + * Creates a new MalformedCookieException with a <tt>null</tt> detail message. + */ + public MalformedCookieException() { + super(); + } + + /** + * Creates a new MalformedCookieException with a specified message string. + * + * @param message The exception detail message + */ + public MalformedCookieException(String message) { + super(message); + } + + /** + * Creates a new MalformedCookieException with the specified detail message and cause. + * + * @param message the exception detail message + * @param cause the <tt>Throwable</tt> that caused this exception, or <tt>null</tt> + * if the cause is unavailable, unknown, or not a <tt>Throwable</tt> + */ + public MalformedCookieException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/src/org/apache/http/cookie/SM.java b/src/org/apache/http/cookie/SM.java new file mode 100644 index 0000000..a7047d5 --- /dev/null +++ b/src/org/apache/http/cookie/SM.java @@ -0,0 +1,48 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/SM.java $ + * $Revision: 582602 $ + * $Date: 2007-10-07 02:35:48 -0700 (Sun, 07 Oct 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +/** + * Constants and static helpers related to the HTTP state management. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public interface SM { + + public static final String COOKIE = "Cookie"; + public static final String COOKIE2 = "Cookie2"; + public static final String SET_COOKIE = "Set-Cookie"; + public static final String SET_COOKIE2 = "Set-Cookie2"; + +} diff --git a/src/org/apache/http/cookie/SetCookie.java b/src/org/apache/http/cookie/SetCookie.java new file mode 100644 index 0000000..d207c48 --- /dev/null +++ b/src/org/apache/http/cookie/SetCookie.java @@ -0,0 +1,115 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/SetCookie.java $ + * $Revision: 617193 $ + * $Date: 2008-01-31 11:26:47 -0800 (Thu, 31 Jan 2008) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +import java.util.Date; + +/** + * This interface represents a <code>SetCookie</code> response header sent by the + * origin server to the HTTP agent in order to maintain a conversational state. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public interface SetCookie extends Cookie { + + void setValue(String value); + + /** + * If a user agent (web browser) presents this cookie to a user, the + * cookie's purpose will be described using this comment. + * + * @param comment + * + * @see #getComment() + */ + void setComment(String comment); + + /** + * Sets expiration date. + * <p><strong>Note:</strong> the object returned by this method is considered + * immutable. Changing it (e.g. using setTime()) could result in undefined + * behaviour. Do so at your peril.</p> + * + * @param expiryDate the {@link Date} after which this cookie is no longer valid. + * + * @see Cookie#getExpiryDate + * + */ + void setExpiryDate (Date expiryDate); + + /** + * Sets the domain attribute. + * + * @param domain The value of the domain attribute + * + * @see Cookie#getDomain + */ + void setDomain(String domain); + + /** + * Sets the path attribute. + * + * @param path The value of the path attribute + * + * @see Cookie#getPath + * + */ + void setPath(String path); + + /** + * Sets the secure attribute of the cookie. + * <p> + * When <tt>true</tt> the cookie should only be sent + * using a secure protocol (https). This should only be set when + * the cookie's originating server used a secure protocol to set the + * cookie's value. + * + * @param secure The value of the secure attribute + * + * @see #isSecure() + */ + void setSecure (boolean secure); + + /** + * Sets the version of the cookie specification to which this + * cookie conforms. + * + * @param version the version of the cookie. + * + * @see Cookie#getVersion + */ + void setVersion(int version); + +} + diff --git a/src/org/apache/http/cookie/SetCookie2.java b/src/org/apache/http/cookie/SetCookie2.java new file mode 100644 index 0000000..cd0420e --- /dev/null +++ b/src/org/apache/http/cookie/SetCookie2.java @@ -0,0 +1,66 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/SetCookie2.java $ + * $Revision: 578408 $ + * $Date: 2007-09-22 04:53:57 -0700 (Sat, 22 Sep 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie; + +/** + * This interface represents a <code>SetCookie2</code> response header sent by the + * origin server to the HTTP agent in order to maintain a conversational state. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @since 4.0 + */ +public interface SetCookie2 extends SetCookie { + + /** + * If a user agent (web browser) presents this cookie to a user, the + * cookie's purpose will be described by the information at this URL. + */ + void setCommentURL(String commentURL); + + /** + * Sets the Port attribute. It restricts the ports to which a cookie + * may be returned in a Cookie request header. + */ + void setPorts(int[] ports); + + /** + * Set the Discard attribute. + * + * Note: <tt>Discard</tt> attribute overrides <tt>Max-age</tt>. + * + * @see #isPersistent() + */ + void setDiscard(boolean discard); + +} + diff --git a/src/org/apache/http/cookie/package.html b/src/org/apache/http/cookie/package.html new file mode 100644 index 0000000..891d9c3 --- /dev/null +++ b/src/org/apache/http/cookie/package.html @@ -0,0 +1,41 @@ +<html> +<head> +<!-- +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/package.html $ + * $Revision: 555193 $ + * $Date: 2007-07-11 00:36:47 -0700 (Wed, 11 Jul 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ +--> +</head> +<body> +The API for client-side state management via cookies, +commonly referred to as <i>HttpCookie</i>. + +</body> +</html> diff --git a/src/org/apache/http/cookie/params/CookieSpecPNames.java b/src/org/apache/http/cookie/params/CookieSpecPNames.java new file mode 100644 index 0000000..6a6f6d0 --- /dev/null +++ b/src/org/apache/http/cookie/params/CookieSpecPNames.java @@ -0,0 +1,68 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/params/CookieSpecPNames.java $ + * $Revision: 578403 $ + * $Date: 2007-09-22 03:56:04 -0700 (Sat, 22 Sep 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie.params; + +/** + * Parameter names for cookie specifications in HttpCookie. + * + * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> + * + * @version $Revision: 578403 $ + * + * @since 4.0 + */ +public interface CookieSpecPNames { + + /** + * Parameter for the date patterns used for parsing. + * <p> + * This parameter expects a value of type {@link java.util.Collection}. + * The collection elements are of type {@link String} + * and must be compatible with the syntax of + * {@link java.text.SimpleDateFormat}. + * </p> + */ + public static final String DATE_PATTERNS = "http.protocol.cookie-datepatterns"; + + /** + * Parameter for Cookie header formatting. + * Defines whether {@link org.apache.http.cookie.Cookie cookies} + * should be put on + * a single {@link org.apache.http.Header request header}. + * If not, each cookie is formatted in a seperate Cookie header. + * <p> + * This parameter expects a value of type {@link Boolean}. + * </p> + */ + public static final String SINGLE_COOKIE_HEADER = "http.protocol.single-cookie-header"; + +} diff --git a/src/org/apache/http/cookie/params/CookieSpecParamBean.java b/src/org/apache/http/cookie/params/CookieSpecParamBean.java new file mode 100644 index 0000000..6016022 --- /dev/null +++ b/src/org/apache/http/cookie/params/CookieSpecParamBean.java @@ -0,0 +1,53 @@ +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/params/CookieSpecParamBean.java $ + * $Revision: 632313 $ + * $Date: 2008-02-29 05:19:50 -0800 (Fri, 29 Feb 2008) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ + +package org.apache.http.cookie.params; + +import java.util.Collection; + +import org.apache.http.params.HttpAbstractParamBean; +import org.apache.http.params.HttpParams; + +public class CookieSpecParamBean extends HttpAbstractParamBean { + + public CookieSpecParamBean (final HttpParams params) { + super(params); + } + + public void setDatePatterns (final Collection <String> patterns) { + params.setParameter(CookieSpecPNames.DATE_PATTERNS, patterns); + } + + public void setSingleHeader (final boolean singleHeader) { + params.setBooleanParameter(CookieSpecPNames.SINGLE_COOKIE_HEADER, singleHeader); + } + +} diff --git a/src/org/apache/http/cookie/params/package.html b/src/org/apache/http/cookie/params/package.html new file mode 100644 index 0000000..e6fb7cd --- /dev/null +++ b/src/org/apache/http/cookie/params/package.html @@ -0,0 +1,40 @@ +<html> +<head> +<!-- +/* + * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/cookie/params/package.html $ + * $Revision: 555193 $ + * $Date: 2007-07-11 00:36:47 -0700 (Wed, 11 Jul 2007) $ + * + * ==================================================================== + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + */ +--> +</head> +<body> +Parameters for configuring <i>HttpCookie</i>. + +</body> +</html> |