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    }