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
015package org.apache.tapestry5.services;
016
017import org.apache.tapestry5.CookieBuilder;
018
019/**
020 * Used by other services to obtain cookie values for the current request, or to write cookie values as part of the
021 * request.  Note that when writing cookies, the cookie's secure flag will match {@link
022 * org.apache.tapestry5.services.Request#isSecure()}.
023 */
024public interface Cookies
025{
026    /**
027     * Returns the value of the first cookie whose name matches. Returns null if no such cookie exists. This method is
028     * only aware of cookies that are part of the incoming request; it does not know about additional cookies added
029     * since then (via {@link #writeCookieValue(String, String)}).
030     */
031    String readCookieValue(String name);
032
033    /**
034     * Creates or updates a cookie value. The value is stored using a max age (in seconds) defined by the symbol
035     * <code>org.apache.tapestry5.default-cookie-max-age</code>. The factory default for this value is the equivalent of
036     * one week.
037     * 
038     * @deprecated Use the {@link CookieBuilder} API, obtained with {@link #getBuilder(String, String)}, instead.
039     */
040
041    void writeCookieValue(String name, String value);
042
043    /**
044     * As with {@link #writeCookieValue(String, String)} but an explicit maximum age may be set.
045     *
046     * @param name   the name of the cookie
047     * @param value  the value to be stored in the cookie
048     * @param maxAge the maximum age, in seconds, to store the cookie
049     * 
050     * @deprecated Use the {@link CookieBuilder} API, obtained with {@link #getBuilder(String, String)}, instead.
051     */
052
053    void writeCookieValue(String name, String value, int maxAge);
054
055    /**
056     * As with {@link #writeCookieValue(String, String)} but an explicit path may be set.
057     * 
058     * @deprecated Use the {@link CookieBuilder} API, obtained with {@link #getBuilder(String, String)}, instead.
059     */
060    void writeCookieValue(String name, String value, String path);
061
062    /**
063     * As with {@link #writeCookieValue(String, String)} but an explicit domain may be set.
064     * 
065     * @deprecated Use the {@link CookieBuilder} API, obtained with {@link #getBuilder(String, String)}, instead.
066     */
067    void writeDomainCookieValue(String name, String value, String domain);
068
069    /**
070     * As with {@link #writeCookieValue(String, String)} but an explicit domain and maximum age may be set.
071     * 
072     * @deprecated Use the {@link CookieBuilder} API, obtained with {@link #getBuilder(String, String)}, instead.
073     */
074    void writeDomainCookieValue(String name, String value, String domain, int maxAge);
075
076    /**
077     * As with {@link #writeCookieValue(String, String, String)} but an explicit domain and path may be set.
078     * 
079     * @deprecated Use the {@link CookieBuilder} API, obtained with {@link #getBuilder(String, String)}, instead.
080     */
081    void writeCookieValue(String name, String value, String path, String domain);
082
083    /**
084     * Removes a previously written cookie, by writing a new cookie with a maxAge of 0. Only deletes a cookie
085     * with the default path and no domain set. For deleting other cookies use {@link CookieBuilder#delete()}.
086     * An instance of the {@link CookieBuilder} API can be obtained with {@link #getBuilder(String, String)}.
087     */
088    void removeCookieValue(String name);
089    
090    /**
091     * Returns a {@link CookieBuilder} to build and write a {@link javax.servlet.http.Cookie}. The default
092     * implementation creates a cookie who's value is stored using a max age (in seconds) defined by
093     * the symbol <code>org.apache.tapestry5.default-cookie-max-age</code>. The factory default for
094     * this value is the equivalent of one week. The default path is the context path (see
095     * {@link Request#getContextPath()}) of the current Request, the default secure setting is to
096     * send the cookie over secure channels only, if the original request was secure (see
097     * {@link Request#isSecure()}
098     * 
099     * @param name
100     *            the name of the cookie
101     * @param value
102     *            the value of the cookie
103     * @return a {@link CookieBuilder} for setting additional cookie attributes and writing it out
104     * 
105     * @since 5.4
106     */
107    CookieBuilder getBuilder(String name, String value);
108}