001    package org.apache.fulcrum.parser;
002    
003    
004    /*
005     * Licensed to the Apache Software Foundation (ASF) under one
006     * or more contributor license agreements.  See the NOTICE file
007     * distributed with this work for additional information
008     * regarding copyright ownership.  The ASF licenses this file
009     * to you under the Apache License, Version 2.0 (the
010     * "License"); you may not use this file except in compliance
011     * with the License.  You may obtain a copy of the License at
012     *
013     *   http://www.apache.org/licenses/LICENSE-2.0
014     *
015     * Unless required by applicable law or agreed to in writing,
016     * software distributed under the License is distributed on an
017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018     * KIND, either express or implied.  See the License for the
019     * specific language governing permissions and limitations
020     * under the License.
021     */
022    
023    
024    import javax.servlet.http.HttpServletRequest;
025    import javax.servlet.http.HttpServletResponse;
026    
027    /**
028     * CookieParser is an interface to a utility to to get and set values
029     * of Cookies on the Client Browser. You can use CookieParser to convert
030     * Cookie values to various types or to set Bean values with setParameters().
031     * Servlet Spec for more information on Cookies.
032     * <p>
033     * Use set() or unset() to Create or Destroy Cookies.
034     * <p>
035     * NOTE: The name= portion of a name=value pair may be converted
036     * to lowercase or uppercase when the object is initialized and when
037     * new data is added.  This behaviour is determined by the url.case.folding
038     * property in TurbineResources.properties.  Adding a name/value pair may
039     * overwrite existing name=value pairs if the names match:
040     *
041     * <pre>
042     * CookieParser cp = data.getCookies();
043     * cp.add("ERROR",1);
044     * cp.add("eRrOr",2);
045     * int result = cp.getInt("ERROR");
046     * </pre>
047     *
048     * In the above example, result is 2.
049     *
050     * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
051     * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
052     * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
053     * @version $Id: CookieParser.java 812786 2009-09-09 07:01:49Z tv $
054     */
055    public interface CookieParser
056        extends ValueParser
057    {
058        static final int AGE_SESSION = -1;
059        static final int AGE_DELETE = 0;
060    
061        /**
062         * Gets the servlet request.
063         *
064         * @return the servlet request object or null.
065         */
066        HttpServletRequest getRequest();
067    
068        /**
069         * Sets the servlet request and response to be parsed.
070         * All previous cookies will be cleared.
071         *
072         * @param request the servlet request object.
073         * @param response the servlet response object
074         */
075        void setData (HttpServletRequest request,
076                      HttpServletResponse response);
077    
078        /**
079         * Set a cookie that will be stored on the client for
080         * the duration of the session.
081         */
082        void set (String name, String value);
083    
084        /**
085         * Set a persisten cookie on the client that will expire
086         * after a maximum age (given in seconds).
087         */
088        void set (String name, String value, int seconds_age);
089    
090        /**
091         * Remove a previously set cookie from the client machine.
092         */
093        void unset (String name);
094    }