001: /* ====================================================================
002: * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
003: *
004: * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * 1. Redistributions of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * 2. Redistributions in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * 3. The end-user documentation included with the redistribution,
019: * if any, must include the following acknowledgment:
020: * "This product includes software developed by Jcorporate Ltd.
021: * (http://www.jcorporate.com/)."
022: * Alternately, this acknowledgment may appear in the software itself,
023: * if and wherever such third-party acknowledgments normally appear.
024: *
025: * 4. "Jcorporate" and product names such as "Expresso" must
026: * not be used to endorse or promote products derived from this
027: * software without prior written permission. For written permission,
028: * please contact info@jcorporate.com.
029: *
030: * 5. Products derived from this software may not be called "Expresso",
031: * or other Jcorporate product names; nor may "Expresso" or other
032: * Jcorporate product names appear in their name, without prior
033: * written permission of Jcorporate Ltd.
034: *
035: * 6. No product derived from this software may compete in the same
036: * market space, i.e. framework, without prior written permission
037: * of Jcorporate Ltd. For written permission, please contact
038: * partners@jcorporate.com.
039: *
040: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
041: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
042: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
043: * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
044: * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
045: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
046: * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
047: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
048: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
049: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
050: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
051: * SUCH DAMAGE.
052: * ====================================================================
053: *
054: * This software consists of voluntary contributions made by many
055: * individuals on behalf of the Jcorporate Ltd. Contributions back
056: * to the project(s) are encouraged when you make modifications.
057: * Please send them to support@jcorporate.com. For more information
058: * on Jcorporate Ltd. and its products, please see
059: * <http://www.jcorporate.com/>.
060: *
061: * Portions of this software are based upon other open source
062: * products and are subject to their respective licenses.
063: */
064: package com.jcorporate.expresso.core.controller.session;
065:
066: import java.io.Serializable;
067: import java.util.Enumeration;
068:
069: /**
070: * A PersistentSession is simply a place to stash some values between
071: * states of a controller object. Different environments may employ different
072: * ways of doing this - the simplest being SimplePersistentSession, where a hashtable does
073: * all the required work.
074: * <p>The typical way to use a PersistentSession is within a controller object
075: * as part of your state handler. You do not instantiate it directly, the controller
076: * framework instantiates the appropriate kind of session for you. [Unless you're directly
077: * creating a controller yourself, such as in a command line environment, in which case, you would
078: * set the session object at say, SimplePersistentSession... if you're getting confused at what
079: * is meant by this, ignore it.] </p>
080: * <p/>
081: * Example Usage:<br/>
082: * <code>
083: * void protected runMyState(ControllerRequest request, ControllerResponse response) throws ControllerException { <br/>
084: * PersistentSesssion session = request.getSession(); <br/>
085: * //Set an attribute that exists only for the current request.<br/>
086: * session.setAttribute("RequestAttribute", "Controller Was Executed"); <br/>
087: * <br/>
088: * //Set an attribute that exists for the entire session <br/>
089: * session.setPersistentAttribute("SessionAttribute","Customer Has Logged In"); <br/>
090: * <br/>
091: * //Set an attribute that persists across requests. [In HTTP sets a cookie] <br/>
092: * session.setClientAttribute("ACookie", "Cookie Data That May Get Encrypted");<br/>
093: * </code>
094: * </p>
095: *
096: * @author Michael Nash
097: * @since Expresso 4.0
098: */
099: public interface PersistentSession extends Serializable {
100: /**
101: * Sets an attribute that is valid for the duration of the request.
102: *
103: * @param attribName The name of the object you wish to set.
104: * @param attribValue the object you want to set.
105: */
106: public void setAttribute(String attribName, Object attribValue);
107:
108: /**
109: * Retrieves the object from the request context.
110: *
111: * @param attribName the name of the object to retrieve
112: * @return the object or null if it doesn't exist.
113: */
114: public Object getAttribute(String attribName);
115:
116: /**
117: * Retrieves all attribute names in the request context.
118: *
119: * @return java.util.Enumeration
120: */
121: public Enumeration getAttributeNames();
122:
123: /**
124: * If in HTTP environment, it sets an encrypted cookie to the client.
125: *
126: * @param attribName the name of the attribute to
127: * @param attribValue the value of the attribute to set.
128: */
129: public void setClientAttribute(String attribName, String attribValue);
130:
131: /**
132: * Retrieves a value of a cookie set on the client's system. It also
133: * decrypts the value with the password you set up in your <code>expresso-config.xml</code>
134: * file.
135: *
136: * @param attribName the name of the cookie to retrieve
137: * @return java.lang.String the value of the cookie or null if the cookie doesn't exist.
138: */
139: public String getClientAttribute(String attribName);
140:
141: /**
142: * Retrieves all attribute names from the session context.
143: *
144: * @return java.util.Enumeration
145: */
146: public Enumeration getPeristentAttributeNames();
147:
148: /**
149: * Saves an attribute to the actual session, rather than simply the response.
150: * Use this for storing objects between requests, but only use it with care
151: * since the extra memory used may bog down systems under high load.
152: *
153: * @param attribName the name of the attribute to set
154: * @param attribValue a <code>Serializable</code> java object.
155: * @see java.io.Serializable
156: */
157: public void setPersistentAttribute(String attribName,
158: 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: }
|