001// Copyright 2012-2013 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;
016
017import org.apache.tapestry5.services.Request;
018
019/**
020 * A fluent API to create and write cookies. Used by the
021 * {@link org.apache.tapestry5.services.Cookies} service.
022 * 
023 * @since 5.4
024 */
025public abstract class CookieBuilder
026{
027    
028    protected final String name;
029    protected final String value;
030    
031    protected String path;
032    protected String domain;
033    protected Integer maxAge;
034    protected Boolean secure;
035    
036    /**
037     * Initialize a new CookieBuilder
038     * 
039     * @param name  the name of the resulting cookie
040     * @param value the value of the resulting cookie
041     */
042    protected CookieBuilder(String name, String value)
043    {
044        this.name = name;
045        this.value = value;
046    }
047
048    /**
049     * Set the path for the cookie to be created. Defaults to {@link Request#getContextPath()}.
050     * @param  path the path for the cookie
051     * @return the modified {@link CookieBuilder}
052     */
053    public CookieBuilder setPath(String path)
054    {
055        this.path = path;
056        return this;
057    }
058
059    /**
060     * Set the domain for the cookie to be created. Will not be set by default.
061     * @param  domain the domain for the cookie
062     * @return the modified {@link CookieBuilder}
063     */
064    public CookieBuilder setDomain(String domain)
065    {
066        this.domain = domain;
067        return this;
068    }
069
070    /**
071     * Set how long the cookie should live. A value of <code>0</code> deletes a cookie, a value of
072     * <code>-1</code> deletes a cookie upon closing the browser. The default is defined by
073     * the symbol <code>org.apache.tapestry5.default-cookie-max-age</code>. The factory default for
074     * this value is the equivalent of one week.
075     * 
076     * @param maxAge
077     *            the cookie's maximum age in seconds
078     * @return the modified {@link CookieBuilder}
079     */
080    public CookieBuilder setMaxAge(int maxAge)
081    {
082        this.maxAge = maxAge;
083        return this;
084    }
085    
086    /**
087     * Set the cookie's secure mode. Defaults to {@link Request#isSecure()}.
088     * 
089     * @param secure whether to send the cookie over a secure channel only
090     * @return the modified {@link CookieBuilder}
091     */
092    public CookieBuilder setSecure(boolean secure)
093    {
094        this.secure = secure;
095        return this;
096    }
097    
098    /**
099     * Sets defaults and writes the cookie to the client.
100     */
101    public abstract void write();
102    
103    /**
104     * Deletes the cookie.
105     */
106    public abstract void delete();
107    
108}