    001    // Copyright 2007, 2009 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    //     http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5.services;
    016
    017    /**
    018     * Used by other services to obtain cookie values for the current request, or to write cookie values as part of the
    019     * request.  Note that when writing cookies, the cookie's secure flag will match {@link
    020     * org.apache.tapestry5.services.Request#isSecure()}.
    021     */
    022    public interface Cookies
    023    {
    024        /**
    025         * Returns the value of the first cookie whose name matches. Returns null if no such cookie exists. This method is
    026         * only aware of cookies that are part of the incoming request; it does not know about additional cookies added
    027         * since then (via {@link #writeCookieValue(String, String)}).
    028         */
    029        String readCookieValue(String name);
    030
    031        /**
    032         * Creates or updates a cookie value. The value is stored using a max age (in seconds) defined by the symbol
    033         * <code>org.apache.tapestry5.default-cookie-max-age</code>. The factory default for this value is the equivalent of
    034         * one week.
    035         */
    036
    037        void writeCookieValue(String name, String value);
    038
    039        /**
    040         * As with {@link #writeCookieValue(String, String)} but an explicit maximum age may be set.
    041         *
    042         * @param name   the name of the cookie
    043         * @param value  the value to be stored in the cookie
    044         * @param maxAge the maximum age, in seconds, to store the cookie
    045         */
    046
    047        void writeCookieValue(String name, String value, int maxAge);
    048
    049        /**
    050         * As with {@link #writeCookieValue(String, String)} but an explicit path may be set.
    051         */
    052        void writeCookieValue(String name, String value, String path);
    053
    054        /**
    055         * As with {@link #writeCookieValue(String, String)} but an explicit domain may be set.
    056         */
    057        void writeDomainCookieValue(String name, String value, String domain);
    058
    059        /**
    060         * As with {@link #writeCookieValue(String, String)} but an explicit domain and maximum age may be set.
    061         */
    062        void writeDomainCookieValue(String name, String value, String domain, int maxAge);
    063
    064        /**
    065         * As with {@link #writeCookieValue(String, String, String)} but an explicit domain and path may be set.
    066         */
    067        void writeCookieValue(String name, String value, String path, String domain);
    068
    069        /**
    070         * Removes a previously written cookie, by writing a new cookie with a maxAge of 0.
    071         */
    072        void removeCookieValue(String name);
    073    }