Source code: com/lutris/appserver/server/session/StandardSessionHome.java
1 /*
2 * Enhydra Java Application Server Project
3 *
4 * The contents of this file are subject to the Enhydra Public License
5 * Version 1.1 (the "License"); you may not use this file except in
6 * compliance with the License. You may obtain a copy of the License on
7 * the Enhydra web site ( http://www.enhydra.org/ ).
8 *
9 * Software distributed under the License is distributed on an "AS IS"
10 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
11 * the License for the specific terms governing rights and limitations
12 * under the License.
13 *
14 * The Initial Developer of the Enhydra Application Server is Lutris
15 * Technologies, Inc. The Enhydra Application Server and portions created
16 * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
17 * All Rights Reserved.
18 *
19 * Contributor(s):
20 *
21 * $Id: StandardSessionHome.java,v 1.3.14.1 2000/10/19 17:59:06 jasona Exp $
22 */
23
24 package com.lutris.appserver.server.session;
25
26 import com.lutris.util.*;
27 import com.lutris.logging.*;
28 import java.util.Enumeration;
29 import java.net.*;
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.session.persistent.PersistentSessionHome
60 * @version $Revision: 1.3.14.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