    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}