    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}