1 package org.apache.fulcrum.parser;
2
3
4 /*
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
20 * under the License.
21 */
22
23
24 import javax.servlet.http.HttpServletRequest;
25 import javax.servlet.http.HttpServletResponse;
26
27 /**
28 * CookieParser is an interface to a utility to to get and set values
29 * of Cookies on the Client Browser. You can use CookieParser to convert
30 * Cookie values to various types or to set Bean values with setParameters().
31 * Servlet Spec for more information on Cookies.
32 * <p>
33 * Use set() or unset() to Create or Destroy Cookies.
34 * <p>
35 * NOTE: The name= portion of a name=value pair may be converted
36 * to lowercase or uppercase when the object is initialized and when
37 * new data is added. This behaviour is determined by the url.case.folding
38 * property in TurbineResources.properties. Adding a name/value pair may
39 * overwrite existing name=value pairs if the names match:
40 *
41 * <pre>
42 * CookieParser cp = data.getCookies();
43 * cp.add("ERROR",1);
44 * cp.add("eRrOr",2);
45 * int result = cp.getInt("ERROR");
46 * </pre>
47 *
48 * In the above example, result is 2.
49 *
50 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
51 * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
52 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
53 * @version $Id$
54 */
55 public interface CookieParser
56 extends ValueParser
57 {
58 static final int AGE_SESSION = -1;
59 static final int AGE_DELETE = 0;
60
61 /**
62 * Gets the servlet request.
63 *
64 * @return the servlet request object or null.
65 */
66 HttpServletRequest getRequest();
67
68 /**
69 * Sets the servlet request and response to be parsed.
70 * All previous cookies will be cleared.
71 *
72 * @param request the servlet request object.
73 * @param response the servlet response object
74 */
75 void setData (HttpServletRequest request,
76 HttpServletResponse response);
77
78 /**
79 * Set a cookie that will be stored on the client for
80 * the duration of the session.
81 *
82 * @param name The name of the cookie
83 * @param value The value of the cooking
84 */
85 void set (String name, String value);
86
87 /**
88 * Set a persistent cookie on the client that will expire
89 * after a maximum age (given in seconds).
90 *
91 * @param name A String for the name
92 * @param value A String for the value
93 * @param seconds_age An int for the age in seconds
94 */
95 void set (String name, String value, int seconds_age);
96
97 /**
98 * Remove a previously set cookie from the client machine.
99 *
100 * @param name the name of the cooking to unset
101 */
102 void unset (String name);
103
104 boolean isValid();
105 }