PersistentSession


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   * &nbsp;&nbsp; PersistentSesssion session = request.getSession(); <br/>
86   * &nbsp;&nbsp; //Set an attribute that exists only for the current request.<br/>
87   * &nbsp;&nbsp; session.setAttribute("RequestAttribute", "Controller Was Executed"); <br/>
88   * <br/>
89   * &nbsp;&nbsp; //Set an attribute that exists for the entire session <br/>
90   * &nbsp;&nbsp; session.setPersistentAttribute("SessionAttribute","Customer Has Logged In"); <br/>
91   * <br/>
92   * &nbsp;&nbsp; //Set an attribute that persists across requests. [In HTTP sets a cookie] <br/>
93   * &nbsp;&nbsp; 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 }
187
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags