StandardSessionHome


1   
2   /*
3    * Enhydra Java Application Server Project
4    *
5    * The contents of this file are subject to the Enhydra Public License
6    * Version 1.1 (the "License"); you may not use this file except in
7    * compliance with the License. You may obtain a copy of the License on
8    * the Enhydra web site ( http://www.enhydra.org/ ).
9    *
10   * Software distributed under the License is distributed on an "AS IS"
11   * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
12   * the License for the specific terms governing rights and limitations
13   * under the License.
14   *
15   * The Initial Developer of the Enhydra Application Server is Lutris
16   * Technologies, Inc. The Enhydra Application Server and portions created
17   * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
18   * All Rights Reserved.
19   *
20   * Contributor(s):
21   *
22   * $Id: StandardSessionHome.java,v 1.1 2005/07/13 11:09:06 slobodan Exp $
23   */
24  
25  package com.lutris.appserver.server.sessionEnhydra;
26  
27  import java.util.Enumeration  ;
28  
29  import com.lutris.appserver.server.session.SessionException;
30  
31  /**
32   * StandardSessionManager uses StandardSessionHome to manage
33   * a collection of sessions.  StandardSessionHome acts both as
34   * a session factory and as a session repository.  The session
35   * manager gains access to instances of sessions via the
36   * home (StandardSessionHome) interface.  The session manager
37   * dynamically loads the home interface.  The implementation
38   * of the home interface that is loaded is specified in the
39   * applications configuration file:
40   *
41   * <ul>
42   * <li><code>SessionHome.Class: {class name}</code><p>
43   * </ul>
44   *
45   * StandardSessionHome manages the state of a session.
46   * A session exists in either of two states: 'active'
47   * or 'passive'.  An 'active' session
48   * is one that is actively being referenced by a thread of
49   * execution (request).  A 'passive' session is one that
50   * is not currently associated with any request (thread).
51   * A session in the 'passive' state may be written to persistent store
52   * until it becomes 'active'.  When a session becomes active,
53   * if it isn't in memory then it can be read from persistent store.<p>
54   *
55   * @see         StandardSession
56   * @see         StandardSessionManager
57   * @see         BasicSessionHome
58   * @see         PagedSessionHome
59   * @see         com.lutris.appserver.server.sessionEnhydra.persistent.PersistentSessionHome
60   * @version $Revision: 1.1 $
61   * @author  Kyle Clark
62   */
63  public interface StandardSessionHome {
64  
65      /**
66       * Creates and returns a new session instance.  The
67       * session is bound to the specified session key.  The
68       * session is also associated with the current thread
69       * and is considered in the 'active' state.  The
70       * session remains in the 'active' state until the
71       * thread puts the session into the 'passive' state..
72       * Only this thread will be able to put the
73       * session into the 'passive' state.
74       *
75       * @param sessionKey the key to associate with the session.
76       * @return the newly created session.
77       * @exception CreateSessionException if the session cannot be
78       *   created.
79       * @exception DuplicateKeyException if the session cannot
80       *   be created because the key is already in use.
81       * @exception SessionException if the session cannot
82       *   be created for some other reason.
83       * @see #passivateSession
84       */
85      public StandardSession createSession(String   sessionKey)
86          throws CreateSessionException, DuplicateKeyException, SessionException;
87  
88      /**
89       * Returns the session bound to the session key.
90       * The session must already be in the 'active' state
91       * and associated with the current thread,
92       * otherwise null is returned.
93       *
94       * @param sessionKey
95       *   the session key for the session.  If the session
96       *   doesn't exist or is not is not bound to the current
97       *   thread then null is returned.
98       * @return
99       *   the session.
100      * @exception SessionException
101      *   if the session cannot be retrieved.
102      * @see #getSession(Thread, String)
103      */
104     public StandardSession getSession(String   sessionKey)
105         throws SessionException;
106 
107     /**
108      * Returns the session bound to the specified
109      * session key.  The session is put into the 'active' state.
110      * The session is also associated with the specified thread.
111      * Only this thread will be able to put the session
112      * back into the 'passive' state once it is done with the
113      * session.
114      *
115      * @param thread the thread that should be associated with
116      *   the session while it is in the active state.  Only this
117      *   thread can put the session back into the passive state.
118      * @param sessionKey
119      *   the session key for the session that will be made
120      *   'active' and returned.  If the session doesn't exist
121      *   then null is returned.
122      * @return
123      *   the session.
124      * @exception SessionException
125      *   if the session cannot be retrieved.
126      * @see #passivateSession
127      */
128     public StandardSession getSession(Thread   thread, String   sessionKey)
129         throws SessionException;
130 
131     /**
132      * Removes a session from the cache.  If the session
133      * doesn't exist the opration is ignored.
134      *
135      * @param sessionKey
136      *   the session key associated with the session.
137      * @exception SessionException
138      *   if the session cannot be retrieved.
139      */
140     public void removeSession(String   sessionKey) throws SessionException;
141 
142     /**
143      * Puts a session into the 'passive' state.  A 'passive'
144      * session may be made persistent.  Only the thread that
145      * put the session into the 'active' state may put
146      * the session into the 'passive' state.
147      *
148      * @param thread the thread that is currently associated
149      *   with the session.
150      * @param sessionKey
151      *   the session key for the session that will be made passive.
152      * @exception SessionException
153      *   if the session cannot be retrieved.
154      */
155     public void passivateSession(Thread   thread, String   sessionKey)
156         throws SessionException;
157 
158     /**
159      * Specifies if a key is currently bound to a session.
160      *
161      * @param sessionKey
162      *   the session key to be tested.
163      * @return
164      *   true if the session key is in use.
165      * @exception SessionException
166      *   if the existence of the key cannot be determined.
167      */
168     public boolean containsKey(String   sessionKey) throws SessionException;
169 
170     /**
171      * Returns the current number of sessions.
172      *
173      * @return
174      *   the 'active' session count.
175      * @exception SessionException
176      *   if the size cannot be determined
177      */
178     public int size() throws SessionException;
179 
180     /**
181      * Returns the current number of sessions that are paged to
182      * persistent store.
183      *
184      * @return
185      *   the 'paged' session count.
186      * @exception SessionException
187      *   if the size cannot be determined
188      */
189     public int pagedSize() throws SessionException;
190 
191     /**
192      * Returns an enumeration of the keys for all the sessions.
193      *
194      * @return
195      *   the enumeration of session keys.
196      * @exception SessionException
197      *   if the session enumeration cannot be retrieved.
198      */
199     public Enumeration   keys() throws SessionException;
200 
201 
202     /**
203      * Shuts dows the session home.
204      */
205     public void shutdown();
206 
207 }
208 
209 
210 
211 
212
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags