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