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