/* 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.
 */
package java.net;

import java.io.IOException;
import java.util.List;
import java.util.Map;

/**
 * This class is an implementation of {@code URLConnection} caches intended
 * primarily for the according stream handler implementations.
 * <p>
 * The system's default cache can be registered by invoking the method {@code
 * setDefault(ResponseCache)} and be retrieved by invoking the method {@code
 * getDefault()}. If {@code URLConnection#useCaches} is set, {@code
 * URLConnection} class will use {@code ResponseCache} to store and get
 * resources.
 * <p>
 * Whether the resource is cached depends on the implementation of {@code
 * ResponseCache}. If so, a {@code CacheResponse} is returned from which the
 * stream handler reads. If the stream handler fails to get a resource from the
 * cache, it must get the resource from its original location.
 * <p>
 * To write to the cache, the protocol handlers call {@code put()}, upon which a
 * {@code CacheRequest} is supplied to which the resources are written.
 *
 * @see #put(URI, URLConnection)
 * @see CacheRequest
 * @see CacheResponse
 * @see URLConnection
 * @see URLStreamHandler
 */
public abstract class ResponseCache {

    /*
     * _defaultResponseCache is used to store default response cache.
     */
    private static ResponseCache _defaultResponseCache = null;

    /*
     * "getResponseCache" permission. getDefault method requires this
     * permission.
     */
    private static NetPermission getResponseCachepermission = new NetPermission(
            "getResponseCache"); //$NON-NLS-1$

    /*
     * "setResponseCache" permission. setDefault method requires this
     * permission.
     */
    private static NetPermission setResponseCachepermission = new NetPermission(
            "setResponseCache"); //$NON-NLS-1$

    /*
     * check getResponseCache permission. getDefault method requires
     * "getResponseCache" permission if a security manager is installed.
     */
    private static void checkGetResponseCachePermission() {
        SecurityManager sm = System.getSecurityManager();
        if (null != sm) {
            sm.checkPermission(getResponseCachepermission);
        }
    }

    /*
     * check setResponseCache permission. setDefault method requires
     * "setResponseCache" permission if a security manager is installed.
     */
    private static void checkSetResponseCachePermission() {
        SecurityManager sm = System.getSecurityManager();
        if (null != sm) {
            sm.checkPermission(setResponseCachepermission);
        }
    }

    /**
     * Creates a new instance of this class.
     */
    public ResponseCache() {
        super();
    }

    /**
     * Gets the default response cache of the system.
     * 
     * @return the default {@code ResponseCache}.
     * @throws SecurityException
     *             if a security manager is installed but it doesn't have the
     *             {@code NetPermission("getResponseCache")}.
     */
    public static ResponseCache getDefault() {
        checkGetResponseCachePermission();
        return _defaultResponseCache;
    }

    /**
     * Sets the default response cache of the system. Removes the system's
     * default {@code ResponseCache} if the parameter {@code responseCache} is
     * set to {@code null}. This setting may be ignored by some non-standard
     * protocols.
     * 
     * @param responseCache
     *            the {@code ResponseCache} instance to set as default or
     *            {@code null} to remove the current default {@code
     *            ResponseCache}.
     * @throws SecurityException
     *             if a security manager is installed but it doesn't have the
     *             {@code NetPermission("setResponseCache")}.
     */
    public static void setDefault(ResponseCache responseCache) {
        checkSetResponseCachePermission();
        _defaultResponseCache = responseCache;
    }

    /**
     * Gets the cached response according to the requesting URI, method and
     * headers.
     * 
     * @param uri
     *            the requesting URI.
     * @param rqstMethod
     *            the requesting method.
     * @param rqstHeaders
     *            a map of requesting headers.
     * @return the {@code CacheResponse} object if the request is available in the cache
     *         or {@code null} otherwise.
     * @throws IOException
     *             if an I/O error occurs while getting the cached data.
     * @throws IllegalArgumentException
     *             if any one of the parameters is set to {@code null}.
     */
    public abstract CacheResponse get(URI uri, String rqstMethod,
            Map<String, List<String>> rqstHeaders) throws IOException;

    /**
     * Allows the protocol handler to cache data after retrieving resources. The
     * {@code ResponseCache} decides whether the resource data should be cached
     * or not. If so, this method returns a {@code CacheRequest} with a {@code
     * WriteableByteChannel} to put the resource data down. Otherwise, this
     * method returns {@code null}.
     * 
     * @param uri
     *            the reference to the requested resource.
     * @param conn
     *            the connection to fetch the response.
     * @return a CacheRequest object with a WriteableByteChannel if the resource
     *         has to be cached, {@code null} otherwise.
     * @throws IOException
     *             if an I/O error occurs while adding the resource.
     * @throws IllegalArgumentException
     *             if any one of the parameters is set to {@code null}.
     */
    public abstract CacheRequest put(URI uri, URLConnection conn)
            throws IOException;
}