/*
 * $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. 
RFC 2109 specification is used per default. Other supported specification
can be  chosen when appropriate or set default when desired
The following specifications are provided:
 

  
BROWSER_COMPATIBILITY: compatible with the common cookie 
  management practices (even if they are not 100% standards compliant)
  
NETSCAPE: Netscape cookie draft compliant
  
RFC_2109: RFC2109 compliant (default)
  
IGNORE_COOKIES: do not automcatically process cookies
 
Author:
Oleg Kalnichevski, Mike Bowler
Since:
2.0/**
 * 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/**
     * 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/** 
     * The Netscape cookie draft compliant policy. 
     * 
     * @since 3.0
     */
    public static final String NETSCAPE = "netscape";

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

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

    
The policy that ignores cookies. 
Since:
3.0/**
     * The policy that ignores cookies. 
     * 
     * @since 3.0
     */
    public static final String IGNORE_COOKIES = "ignoreCookies";
    
    
The default cookie policy. 
Since:
3.0/** 
     * 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 COMPATIBILITY policy provides high compatibilty 
with common cookie management of popular HTTP agents.
Deprecated:
Use BROWSER_COMPATIBILITY/**
     * 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 NETSCAPE_DRAFT Netscape draft compliant policy.
Deprecated:
Use NETSCAPE/** 
     * The <tt>NETSCAPE_DRAFT</tt> Netscape draft compliant policy.
     * 
     * @deprecated Use {@link #NETSCAPE} 
     */
    public static final int NETSCAPE_DRAFT = 1;

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

    
The RFC2965 RFC 2965 compliant policy.
Deprecated:
Use RFC_2965/**
     * 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 DEFAULT/**
     * The default cookie policy.
     *  
     * @deprecated Use {@link #DEFAULT} 
     */
    private static int defaultPolicy = RFC2109;

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

    
Registers a new 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 cookie specification from getCookieSpec(String). 
Params:
id – the identifier for this specification
clazz – the cookie specification class to register
See Also:
getCookieSpec(String)
Since:
3.0/**
     * 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 cookie specification with the given ID. 
Params:
id – the ID of the cookie specification to unregister
Since:
3.0/**
     * 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 cookie specification with the given ID. 
Params:
id – the cookie specification ID
Throws:
IllegalStateException – if a policy with the ID cannot be found
Returns:
cookie specification
Since:
3.0/**
     * 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);
        }
    } 

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

    
Params:
policy – new default cookie policy
See Also:
DEFAULT
Deprecated:
Use registerCookieSpec(String, Class)/**
     * @param policy new default cookie policy
     * 
     * @deprecated Use {@link CookiePolicy#registerCookieSpec(String, Class)}
     * @see #DEFAULT 
     */
    public static void setDefaultPolicy(int policy) {
        defaultPolicy = policy;
    }
    
    
Params:
policy – cookie policy to get the CookieSpec for
Returns:
cookie specification interface for the given policy
Deprecated:
Use getCookieSpec(String)/**
     * @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 cookie specification registered as DEFAULT. If no default cookie specification has been registered, RFC2109 specification is returned. 
See Also:
DEFAULT
Returns:
default cookie specification/**
     * 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.
Supported versions:

 
version 0 corresponds to the Netscape draft
 
version 1 corresponds to the RFC 2109
 
Any other cookie value coresponds to the default spec

Params:
ver – the cookie version to get the spec for
Returns:
cookie specification interface intended for processing 
 cookies with the given version
Deprecated:
Use getCookieSpec(String)/**
     * 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(); 
        }
    }

    
Returns:
cookie specification interface that provides high compatibilty 
with common cookie management of popular HTTP agents
Deprecated:
Use getCookieSpec(String)/**
     * @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.
Returns:
array of registered cookie policy names
Since:
3.1/**
     * 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()]); 
    }
    
}