001: /*
002: * Copyright 1999,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.catalina;
018:
019: import java.beans.PropertyChangeListener;
020: import java.io.IOException;
021:
022: /**
023: * A <b>Manager</b> manages the pool of Sessions that are associated with a
024: * particular Container. Different Manager implementations may support
025: * value-added features such as the persistent storage of session data,
026: * as well as migrating sessions for distributable web applications.
027: * <p>
028: * In order for a <code>Manager</code> implementation to successfully operate
029: * with a <code>Context</code> implementation that implements reloading, it
030: * must obey the following constraints:
031: * <ul>
032: * <li>Must implement <code>Lifecycle</code> so that the Context can indicate
033: * that a restart is required.
034: * <li>Must allow a call to <code>stop()</code> to be followed by a call to
035: * <code>start()</code> on the same <code>Manager</code> instance.
036: * </ul>
037: *
038: * @author Craig R. McClanahan
039: * @version $Revision: 1.11 $ $Date: 2004/05/26 15:28:21 $
040: */
041:
042: public interface Manager {
043:
044: // ------------------------------------------------------------- Properties
045:
046: /**
047: * Return the Container with which this Manager is associated.
048: */
049: public Container getContainer();
050:
051: /**
052: * Set the Container with which this Manager is associated.
053: *
054: * @param container The newly associated Container
055: */
056: public void setContainer(Container container);
057:
058: /**
059: * Return the DefaultContext with which this Manager is associated.
060: */
061: public DefaultContext getDefaultContext();
062:
063: /**
064: * Set the DefaultContext with which this Manager is associated.
065: *
066: * @param defaultContext The newly associated DefaultContext
067: */
068: public void setDefaultContext(DefaultContext defaultContext);
069:
070: /**
071: * Return the distributable flag for the sessions supported by
072: * this Manager.
073: */
074: public boolean getDistributable();
075:
076: /**
077: * Set the distributable flag for the sessions supported by this
078: * Manager. If this flag is set, all user data objects added to
079: * sessions associated with this manager must implement Serializable.
080: *
081: * @param distributable The new distributable flag
082: */
083: public void setDistributable(boolean distributable);
084:
085: /**
086: * Return descriptive information about this Manager implementation and
087: * the corresponding version number, in the format
088: * <code><description>/<version></code>.
089: */
090: public String getInfo();
091:
092: /**
093: * Return the default maximum inactive interval (in seconds)
094: * for Sessions created by this Manager.
095: */
096: public int getMaxInactiveInterval();
097:
098: /**
099: * Set the default maximum inactive interval (in seconds)
100: * for Sessions created by this Manager.
101: *
102: * @param interval The new default value
103: */
104: public void setMaxInactiveInterval(int interval);
105:
106: /**
107: * Gets the session id length (in bytes) of Sessions created by
108: * this Manager.
109: *
110: * @return The session id length
111: */
112: public int getSessionIdLength();
113:
114: /**
115: * Sets the session id length (in bytes) for Sessions created by this
116: * Manager.
117: *
118: * @param idLength The session id length
119: */
120: public void setSessionIdLength(int idLength);
121:
122: /**
123: * Returns the total number of sessions created by this manager.
124: *
125: * @return Total number of sessions created by this manager.
126: */
127: public int getSessionCounter();
128:
129: /**
130: * Sets the total number of sessions created by this manager.
131: *
132: * @param sessionCounter Total number of sessions created by this manager.
133: */
134: public void setSessionCounter(int sessionCounter);
135:
136: /**
137: * Gets the maximum number of sessions that have been active at the same
138: * time.
139: *
140: * @return Maximum number of sessions that have been active at the same
141: * time
142: */
143: public int getMaxActive();
144:
145: /**
146: * (Re)sets the maximum number of sessions that have been active at the
147: * same time.
148: *
149: * @param maxActive Maximum number of sessions that have been active at
150: * the same time.
151: */
152: public void setMaxActive(int maxActive);
153:
154: /**
155: * Gets the number of currently active sessions.
156: *
157: * @return Number of currently active sessions
158: */
159: public int getActiveSessions();
160:
161: /**
162: * Gets the number of sessions that have expired.
163: *
164: * @return Number of sessions that have expired
165: */
166: public int getExpiredSessions();
167:
168: /**
169: * Sets the number of sessions that have expired.
170: *
171: * @param expiredSessions Number of sessions that have expired
172: */
173: public void setExpiredSessions(int expiredSessions);
174:
175: /**
176: * Gets the number of sessions that were not created because the maximum
177: * number of active sessions was reached.
178: *
179: * @return Number of rejected sessions
180: */
181: public int getRejectedSessions();
182:
183: /**
184: * Sets the number of sessions that were not created because the maximum
185: * number of active sessions was reached.
186: *
187: * @param rejectedSessions Number of rejected sessions
188: */
189: public void setRejectedSessions(int rejectedSessions);
190:
191: // --------------------------------------------------------- Public Methods
192:
193: /**
194: * Add this Session to the set of active Sessions for this Manager.
195: *
196: * @param session Session to be added
197: */
198: public void add(Session session);
199:
200: /**
201: * Add a property change listener to this component.
202: *
203: * @param listener The listener to add
204: */
205: public void addPropertyChangeListener(
206: PropertyChangeListener listener);
207:
208: /**
209: * Get a session from the recycled ones or create a new empty one.
210: * The PersistentManager manager does not need to create session data
211: * because it reads it from the Store.
212: */
213: public Session createEmptySession();
214:
215: /**
216: * Construct and return a new session object, based on the default
217: * settings specified by this Manager's properties. The session
218: * id will be assigned by this method, and available via the getId()
219: * method of the returned session. If a new session cannot be created
220: * for any reason, return <code>null</code>.
221: *
222: * @exception IllegalStateException if a new session cannot be
223: * instantiated for any reason
224: */
225: public Session createSession();
226:
227: /**
228: * Return the active Session, associated with this Manager, with the
229: * specified session id (if any); otherwise return <code>null</code>.
230: *
231: * @param id The session id for the session to be returned
232: *
233: * @exception IllegalStateException if a new session cannot be
234: * instantiated for any reason
235: * @exception IOException if an input/output error occurs while
236: * processing this request
237: */
238: public Session findSession(String id) throws IOException;
239:
240: /**
241: * Return the set of active Sessions associated with this Manager.
242: * If this Manager has no active Sessions, a zero-length array is returned.
243: */
244: public Session[] findSessions();
245:
246: /**
247: * Load any currently active sessions that were previously unloaded
248: * to the appropriate persistence mechanism, if any. If persistence is not
249: * supported, this method returns without doing anything.
250: *
251: * @exception ClassNotFoundException if a serialized class cannot be
252: * found during the reload
253: * @exception IOException if an input/output error occurs
254: */
255: public void load() throws ClassNotFoundException, IOException;
256:
257: /**
258: * Remove this Session from the active Sessions for this Manager.
259: *
260: * @param session Session to be removed
261: */
262: public void remove(Session session);
263:
264: /**
265: * Remove a property change listener from this component.
266: *
267: * @param listener The listener to remove
268: */
269: public void removePropertyChangeListener(
270: PropertyChangeListener listener);
271:
272: /**
273: * Save any currently active sessions in the appropriate persistence
274: * mechanism, if any. If persistence is not supported, this method
275: * returns without doing anything.
276: *
277: * @exception IOException if an input/output error occurs
278: */
279: public void unload() throws IOException;
280:
281: /**
282: * This method will be invoked by the context/container on a periodic
283: * basis and allows the manager to implement
284: * a method that executes periodic tasks, such as expiring sessions etc.
285: */
286: public void backgroundProcess();
287:
288: }
|