001: /*
002: * Enhydra Java Application Server Project
003: *
004: * The contents of this file are subject to the Enhydra Public License
005: * Version 1.1 (the "License"); you may not use this file except in
006: * compliance with the License. You may obtain a copy of the License on
007: * the Enhydra web site ( http://www.enhydra.org/ ).
008: *
009: * Software distributed under the License is distributed on an "AS IS"
010: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
011: * the License for the specific terms governing rights and limitations
012: * under the License.
013: *
014: * The Initial Developer of the Enhydra Application Server is Lutris
015: * Technologies, Inc. The Enhydra Application Server and portions created
016: * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
017: * All Rights Reserved.
018: *
019: * Contributor(s):
020: *
021: * $Id: StandardSessionHome.java,v 1.2 2006-06-15 13:40:47 sinisa Exp $
022: */
023:
024: package com.lutris.appserver.server.sessionEnhydra;
025:
026: import java.util.Enumeration;
027:
028: import com.lutris.appserver.server.session.SessionException;
029:
030: /**
031: * StandardSessionManager uses StandardSessionHome to manage
032: * a collection of sessions. StandardSessionHome acts both as
033: * a session factory and as a session repository. The session
034: * manager gains access to instances of sessions via the
035: * home (StandardSessionHome) interface. The session manager
036: * dynamically loads the home interface. The implementation
037: * of the home interface that is loaded is specified in the
038: * applications configuration file:
039: *
040: * <ul>
041: * <li><code>SessionHome.Class: {class name}</code><p>
042: * </ul>
043: *
044: * StandardSessionHome manages the state of a session.
045: * A session exists in either of two states: 'active'
046: * or 'passive'. An 'active' session
047: * is one that is actively being referenced by a thread of
048: * execution (request). A 'passive' session is one that
049: * is not currently associated with any request (thread).
050: * A session in the 'passive' state may be written to persistent store
051: * until it becomes 'active'. When a session becomes active,
052: * if it isn't in memory then it can be read from persistent store.<p>
053: *
054: * @see StandardSession
055: * @see StandardSessionManager
056: * @see BasicSessionHome
057: * @see PagedSessionHome
058: * @see com.lutris.appserver.server.sessionEnhydra.persistent.PersistentSessionHome
059: * @version $Revision: 1.2 $
060: * @author Kyle Clark
061: */
062: public interface StandardSessionHome {
063:
064: /**
065: * Creates and returns a new session instance. The
066: * session is bound to the specified session key. The
067: * session is also associated with the current thread
068: * and is considered in the 'active' state. The
069: * session remains in the 'active' state until the
070: * thread puts the session into the 'passive' state..
071: * Only this thread will be able to put the
072: * session into the 'passive' state.
073: *
074: * @param sessionKey the key to associate with the session.
075: * @return the newly created session.
076: * @exception CreateSessionException if the session cannot be
077: * created.
078: * @exception DuplicateKeyException if the session cannot
079: * be created because the key is already in use.
080: * @exception SessionException if the session cannot
081: * be created for some other reason.
082: * @see #passivateSession
083: */
084: public StandardSession createSession(String sessionKey)
085: throws CreateSessionException, DuplicateKeyException,
086: SessionException;
087:
088: /**
089: * Returns the session bound to the session key.
090: * The session must already be in the 'active' state
091: * and associated with the current thread,
092: * otherwise null is returned.
093: *
094: * @param sessionKey
095: * the session key for the session. If the session
096: * doesn't exist or is not is not bound to the current
097: * thread then null is returned.
098: * @return
099: * 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)
141: throws SessionException;
142:
143: /**
144: * Puts a session into the 'passive' state. A 'passive'
145: * session may be made persistent. Only the thread that
146: * put the session into the 'active' state may put
147: * the session into the 'passive' state.
148: *
149: * @param thread the thread that is currently associated
150: * with the session.
151: * @param sessionKey
152: * the session key for the session that will be made passive.
153: * @exception SessionException
154: * if the session cannot be retrieved.
155: */
156: public void passivateSession(Thread thread, String sessionKey)
157: throws SessionException;
158:
159: /**
160: * Specifies if a key is currently bound to a session.
161: *
162: * @param sessionKey
163: * the session key to be tested.
164: * @return
165: * true if the session key is in use.
166: * @exception SessionException
167: * if the existence of the key cannot be determined.
168: */
169: public boolean containsKey(String sessionKey)
170: throws SessionException;
171:
172: /**
173: * Returns the current number of sessions.
174: *
175: * @return
176: * the 'active' session count.
177: * @exception SessionException
178: * if the size cannot be determined
179: */
180: public int size() throws SessionException;
181:
182: /**
183: * Returns the current number of sessions that are paged to
184: * persistent store.
185: *
186: * @return
187: * the 'paged' session count.
188: * @exception SessionException
189: * if the size cannot be determined
190: */
191: public int pagedSize() throws SessionException;
192:
193: /**
194: * Returns an enumeration of the keys for all the sessions.
195: *
196: * @return
197: * the enumeration of session keys.
198: * @exception SessionException
199: * if the session enumeration cannot be retrieved.
200: */
201: public Enumeration keys() throws SessionException;
202:
203: /**
204: * Shuts dows the session home.
205: */
206: public void shutdown();
207:
208: }
|