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 }