Source code: com/jcorporate/expresso/core/controller/session/PersistentSession.java
1 /* ====================================================================
2 * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
3 *
4 * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 *
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
16 * distribution.
17 *
18 * 3. The end-user documentation included with the redistribution,
19 * if any, must include the following acknowledgment:
20 * "This product includes software developed by Jcorporate Ltd.
21 * (http://www.jcorporate.com/)."
22 * Alternately, this acknowledgment may appear in the software itself,
23 * if and wherever such third-party acknowledgments normally appear.
24 *
25 * 4. "Jcorporate" and product names such as "Expresso" must
26 * not be used to endorse or promote products derived from this
27 * software without prior written permission. For written permission,
28 * please contact info@jcorporate.com.
29 *
30 * 5. Products derived from this software may not be called "Expresso",
31 * or other Jcorporate product names; nor may "Expresso" or other
32 * Jcorporate product names appear in their name, without prior
33 * written permission of Jcorporate Ltd.
34 *
35 * 6. No product derived from this software may compete in the same
36 * market space, i.e. framework, without prior written permission
37 * of Jcorporate Ltd. For written permission, please contact
38 * partners@jcorporate.com.
39 *
40 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43 * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
44 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
45 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
46 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51 * SUCH DAMAGE.
52 * ====================================================================
53 *
54 * This software consists of voluntary contributions made by many
55 * individuals on behalf of the Jcorporate Ltd. Contributions back
56 * to the project(s) are encouraged when you make modifications.
57 * Please send them to support@jcorporate.com. For more information
58 * on Jcorporate Ltd. and its products, please see
59 * <http://www.jcorporate.com/>.
60 *
61 * Portions of this software are based upon other open source
62 * products and are subject to their respective licenses.
63 */
64 package com.jcorporate.expresso.core.controller.session;
65
66 import java.io.Serializable;
67 import java.util.Enumeration;
68
69
70 /**
71 * A PersistentSession is simply a place to stash some values between
72 * states of a controller object. Different environments may employ different
73 * ways of doing this - the simplest being SimplePersistentSession, where a hashtable does
74 * all the required work.
75 * <p>The typical way to use a PersistentSession is within a controller object
76 * as part of your state handler. You do not instantiate it directly, the controller
77 * framework instantiates the appropriate kind of session for you. [Unless you're directly
78 * creating a controller yourself, such as in a command line environment, in which case, you would
79 * set the session object at say, SimplePersistentSession... if you're getting confused at what
80 * is meant by this, ignore it.] </p>
81 * <p/>
82 * Example Usage:<br/>
83 * <code>
84 * void protected runMyState(ControllerRequest request, ControllerResponse response) throws ControllerException { <br/>
85 * PersistentSesssion session = request.getSession(); <br/>
86 * //Set an attribute that exists only for the current request.<br/>
87 * session.setAttribute("RequestAttribute", "Controller Was Executed"); <br/>
88 * <br/>
89 * //Set an attribute that exists for the entire session <br/>
90 * session.setPersistentAttribute("SessionAttribute","Customer Has Logged In"); <br/>
91 * <br/>
92 * //Set an attribute that persists across requests. [In HTTP sets a cookie] <br/>
93 * session.setClientAttribute("ACookie", "Cookie Data That May Get Encrypted");<br/>
94 * </code>
95 * </p>
96 *
97 * @author Michael Nash
98 * @since Expresso 4.0
99 */
100 public interface PersistentSession extends Serializable {
101 /**
102 * Sets an attribute that is valid for the duration of the request.
103 *
104 * @param attribName The name of the object you wish to set.
105 * @param attribValue the object you want to set.
106 */
107 public void setAttribute(String attribName, Object attribValue);
108
109 /**
110 * Retrieves the object from the request context.
111 *
112 * @param attribName the name of the object to retrieve
113 * @return the object or null if it doesn't exist.
114 */
115 public Object getAttribute(String attribName);
116
117 /**
118 * Retrieves all attribute names in the request context.
119 *
120 * @return java.util.Enumeration
121 */
122 public Enumeration getAttributeNames();
123
124 /**
125 * If in HTTP environment, it sets an encrypted cookie to the client.
126 *
127 * @param attribName the name of the attribute to
128 * @param attribValue the value of the attribute to set.
129 */
130 public void setClientAttribute(String attribName, String attribValue);
131
132 /**
133 * Retrieves a value of a cookie set on the client's system. It also
134 * decrypts the value with the password you set up in your <code>expresso-config.xml</code>
135 * file.
136 *
137 * @param attribName the name of the cookie to retrieve
138 * @return java.lang.String the value of the cookie or null if the cookie doesn't exist.
139 */
140 public String getClientAttribute(String attribName);
141
142 /**
143 * Retrieves all attribute names from the session context.
144 *
145 * @return java.util.Enumeration
146 */
147 public Enumeration getPeristentAttributeNames();
148
149 /**
150 * Saves an attribute to the actual session, rather than simply the response.
151 * Use this for storing objects between requests, but only use it with care
152 * since the extra memory used may bog down systems under high load.
153 *
154 * @param attribName the name of the attribute to set
155 * @param attribValue a <code>Serializable</code> java object.
156 * @see java.io.Serializable
157 */
158 public void setPersistentAttribute(String attribName, Object attribValue);
159
160 /**
161 * Retrieves the object from the session context.
162 *
163 * @param attribName the name of the object to retrieve
164 * @return the object or null if it doesn't exist.
165 */
166 public Object getPersistentAttribute(String attribName);
167
168 /**
169 * Clear out the session. Invalidates the entire session.
170 */
171 public void invalidate();
172
173 /**
174 * Clears an attribute from the request context
175 *
176 * @param attribName the name of the attribute to remove.
177 */
178 public void removeAttribute(String attribName);
179
180 /**
181 * Clears an attribute from the session context
182 *
183 * @param attribName the name of the attribute to remove.
184 */
185 public void removePersistentAttribute(String attribName);
186 }