httpclient/cookie/CookiePolicy.java

/*
 * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/cookie/CookiePolicy.java,v 1.15 2004/09/14 20:11:31 olegk Exp $
 * $Revision: 480424 $
 * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 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.commons.httpclient.cookie;

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

/**
 * Cookie management policy class. The cookie policy provides corresponding
 * cookie management interfrace for a given type or version of cookie.
 * <p>RFC 2109 specification is used per default. Other supported specification
 * can be  chosen when appropriate or set default when desired
 * <p>The following specifications are provided:
 *  <ul>
 *   <li><tt>BROWSER_COMPATIBILITY</tt>: compatible with the common cookie
 *   management practices (even if they are not 100% standards compliant)
 *   <li><tt>NETSCAPE</tt>: Netscape cookie draft compliant
 *   <li><tt>RFC_2109</tt>: RFC2109 compliant (default)
 *   <li><tt>IGNORE_COOKIES</tt>: do not automcatically process cookies
 *  </ul>
 *
 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
 *
 * @since 2.0
 */
public abstract class CookiePolicy {

    private static Map SPECS = Collections.synchronizedMap(new HashMap());

    /**
     * The policy that provides high degree of compatibilty
     * with common cookie management of popular HTTP agents.
     *
     * @since 3.0
     */
    public static final String BROWSER_COMPATIBILITY = "compatibility";

    /**
     * The Netscape cookie draft compliant policy.
     *
     * @since 3.0
     */
    public static final String NETSCAPE = "netscape";

    /**
     * The RFC 2109 compliant policy.
     *
     * @since 3.0
     */
    public static final String RFC_2109 = "rfc2109";

    /**
     * The RFC 2965 compliant policy.
     *
     * @since 3.0
     */
    public static final String RFC_2965 = "rfc2965";

    /**
     * The policy that ignores cookies.
     *
     * @since 3.0
     */
    public static final String IGNORE_COOKIES = "ignoreCookies";

    /**
     * The default cookie policy.
     *
     * @since 3.0
     */
    public static final String DEFAULT = "default";

    static {
        CookiePolicy.registerCookieSpec(DEFAULT, RFC2109Spec.class);
        CookiePolicy.registerCookieSpec(RFC_2109, RFC2109Spec.class);
        CookiePolicy.registerCookieSpec(RFC_2965, RFC2965Spec.class);
        CookiePolicy.registerCookieSpec(BROWSER_COMPATIBILITY, CookieSpecBase.class);
        CookiePolicy.registerCookieSpec(NETSCAPE, NetscapeDraftSpec.class);
        CookiePolicy.registerCookieSpec(IGNORE_COOKIES, IgnoreCookiesSpec.class);
    }

    /**
     * The <tt>COMPATIBILITY</tt> policy provides high compatibilty
     * with common cookie management of popular HTTP agents.
     *
     * @deprecated Use {@link #BROWSER_COMPATIBILITY}
     */
    public static final int COMPATIBILITY = 0;

    /**
     * The <tt>NETSCAPE_DRAFT</tt> Netscape draft compliant policy.
     *
     * @deprecated Use {@link #NETSCAPE}
     */
    public static final int NETSCAPE_DRAFT = 1;

    /**
     * The <tt>RFC2109</tt> RFC 2109 compliant policy.
     *
     * @deprecated Use {@link #RFC_2109}
     */
    public static final int RFC2109 = 2;

    /**
     * The <tt>RFC2965</tt> RFC 2965 compliant policy.
     *
     * @deprecated Use {@link #RFC_2965}
     */
    public static final int RFC2965 = 3;

    /**
     * The default cookie policy.
     *
     * @deprecated Use {@link #DEFAULT}
     */
    private static int defaultPolicy = RFC2109;

    /** Log object. */
    protected static final Log LOG = LogFactory.getLog(CookiePolicy.class);

    /**
     * Registers a new {@link CookieSpec cookie specification} with the given identifier.
     * If a specification with the given ID already exists it will be overridden.
     * This ID is the same one used to retrieve the {@link CookieSpec cookie specification}
     * from {@link #getCookieSpec(String)}.
     *
     * @param id the identifier for this specification
     * @param clazz the {@link CookieSpec cookie specification} class to register
     *
     * @see #getCookieSpec(String)
     *
     * @since 3.0
     */
    public static void registerCookieSpec(final String id, final Class clazz) {
         if (id == null) {
             throw new IllegalArgumentException("Id may not be null");
         }
        if (clazz == null) {
            throw new IllegalArgumentException("Cookie spec class may not be null");
        }
        SPECS.put(id.toLowerCase(), clazz);
    }

    /**
     * Unregisters the {@link CookieSpec cookie specification} with the given ID.
     *
     * @param id the ID of the {@link CookieSpec cookie specification} to unregister
     *
     * @since 3.0
     */
    public static void unregisterCookieSpec(final String id) {
         if (id == null) {
             throw new IllegalArgumentException("Id may not be null");
         }
         SPECS.remove(id.toLowerCase());
    }

    /**
     * Gets the {@link CookieSpec cookie specification} with the given ID.
     *
     * @param id the {@link CookieSpec cookie specification} ID
     *
     * @return {@link CookieSpec cookie specification}
     *
     * @throws IllegalStateException if a policy with the ID cannot be found
     *
     * @since 3.0
     */
    public static CookieSpec getCookieSpec(final String id)
        throws IllegalStateException {

        if (id == null) {
            throw new IllegalArgumentException("Id may not be null");
        }
        Class clazz = (Class)SPECS.get(id.toLowerCase());

        if (clazz != null) {
            try {
                return (CookieSpec)clazz.newInstance();
            } catch (Exception e) {
                LOG.error("Error initializing cookie spec: " + id, e);
                throw new IllegalStateException(id +
                    " cookie spec implemented by " +
                    clazz.getName() + " could not be initialized");
            }
        } else {
            throw new IllegalStateException("Unsupported cookie spec " + id);
        }
    }

    /**
     * @return default cookie policy
     *
     * @deprecated Use {@link #getDefaultSpec()}
     *
     * @see #getDefaultSpec()
     */
    public static int getDefaultPolicy() {
        return defaultPolicy;
    }


    /**
     * @param policy new default cookie policy
     *
     * @deprecated Use {@link CookiePolicy#registerCookieSpec(String, Class)}
     * @see #DEFAULT
     */
    public static void setDefaultPolicy(int policy) {
        defaultPolicy = policy;
    }

    /**
     * @param policy cookie policy to get the CookieSpec for
     * @return cookie specification interface for the given policy
     *
     * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
     */
    public static CookieSpec getSpecByPolicy(int policy) {
        switch(policy) {
            case COMPATIBILITY:
                return new CookieSpecBase();
            case NETSCAPE_DRAFT:
                return new NetscapeDraftSpec();
            case RFC2109:
                return new RFC2109Spec();
            case RFC2965:
                return new RFC2965Spec();
            default:
                return getDefaultSpec();
        }
    }


    /**
     * Returns {@link CookieSpec cookie specification} registered as {@link #DEFAULT}.
     * If no default {@link CookieSpec cookie specification} has been registered,
     * {@link RFC2109Spec RFC2109 specification} is returned.
     *
     * @return default {@link CookieSpec cookie specification}
     *
     * @see #DEFAULT
     */
    public static CookieSpec getDefaultSpec() {
        try {
            return getCookieSpec(DEFAULT);
        } catch (IllegalStateException e) {
            LOG.warn("Default cookie policy is not registered");
            return new RFC2109Spec();
        }
    }


    /**
     * Gets the CookieSpec for a particular cookie version.
     *
     * <p>Supported versions:
     * <ul>
     *  <li><tt>version 0</tt> corresponds to the Netscape draft
     *  <li><tt>version 1</tt> corresponds to the RFC 2109
     *  <li>Any other cookie value coresponds to the default spec
     * <ul>
     *
     * @param ver the cookie version to get the spec for
     * @return cookie specification interface intended for processing
     *  cookies with the given version
     *
     * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
     */
    public static CookieSpec getSpecByVersion(int ver) {
        switch(ver) {
            case 0:
                return new NetscapeDraftSpec();
            case 1:
                return new RFC2109Spec();
            default:
                return getDefaultSpec();
        }
    }

    /**
     * @return cookie specification interface that provides high compatibilty
     * with common cookie management of popular HTTP agents
     *
     * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
     */
    public static CookieSpec getCompatibilitySpec() {
        return getSpecByPolicy(COMPATIBILITY);
    }

    /**
     * Obtains the currently registered cookie policy names.
     *
     * 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 array of registered cookie policy names
     *
     * @since 3.1
     */
    public static String[] getRegisteredCookieSpecs(){
            return (String[]) SPECS.keySet().toArray(new String [SPECS.size()]);
    }

}