/* 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.util.List;

/**
 * A CookieStore object is a repository for cookies.
 *
 * CookieManager will store cookies of every incoming HTTP response into
 * CookieStore, and retrieve cookies for every outgoing HTTP request.Expired
 * HttpCookies should be removed from this store by themselves.
 *
 * @since 1.6
 */
public interface CookieStore {

    /**
     * Saves a HTTP cookie to this store. This is called for every incoming HTTP
     * response.
     *
     * A cookie may or may not has an associated URI. If not, the cookie's
     * domain and path attribute will show cradleland. If there is an
     * associated URI and no domain and path attribute are speicifed for the
     * cookie, the given URI will indicate where this cookie comes from.
     *
     * If a cookie corresponding to the given URI already exists, then it is
     * replaced with the new one.
     *
     * @param uri
     *            the uri associated with the specified cookie. A null value
     *            indicates the cookie is not associated with a URI
     * @param cookie
     *            the cookie to be stored
     */
    void add(URI uri, HttpCookie cookie);

    /**
     * Retrieves cookies that match the specified URI. Return not expired cookies.
     * For every outgoing HTTP request, this method will be called.
     *
     * @param uri
     *            the uri this cookie associated with. If null, this cookie will
     *            not be associated with an URI
     * @return an immutable list of HttpCookies, return empty list if no cookies
     *         match the given URI
     * @throws NullPointerException
     *             if uri is null
     */
    List<HttpCookie> get(URI uri);

    /**
     * Get all cookies in cookie store which are not expired.
     *
     * @return an empty list if there's no http cookie in store, or an immutable
     *         list of cookies
     */
    List<HttpCookie> getCookies();

    /**
     * Get a set of URIs, which is composed of associated URI with all the
     * cookies in the store.
     *
     * @return zero-length list if no cookie in the store is associated with any
     *         URIs, otherwise an immutable list of URIs.
     */
    List<URI> getURIs();

    /**
     * Remove the specified cookie from the store.
     *
     * @param uri
     *            the uri associated with the specified cookie. If the cookie is
     *            not associated with an URI when added, uri should be null;
     *            otherwise the uri should be non-null.
     * @param cookie
     *            the cookie to be removed
     * @return true if the specified cookie is contained in this store and
     *         removed successfully
     */
    boolean remove(URI uri, HttpCookie cookie);

    /**
     * Clear this cookie store.
     *
     * @return true if any cookies were removed as a result of this call.
     */
    boolean removeAll();
}