| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| |
| package org.apache.catalina; |
| |
| |
| import java.beans.PropertyChangeListener; |
| import java.io.IOException; |
| |
| |
| /** |
| * A <b>Manager</b> manages the pool of Sessions that are associated with a |
| * particular Context. Different Manager implementations may support |
| * value-added features such as the persistent storage of session data, |
| * as well as migrating sessions for distributable web applications. |
| * <p> |
| * In order for a <code>Manager</code> implementation to successfully operate |
| * with a <code>Context</code> implementation that implements reloading, it |
| * must obey the following constraints: |
| * <ul> |
| * <li>Must implement <code>Lifecycle</code> so that the Context can indicate |
| * that a restart is required. |
| * <li>Must allow a call to <code>stop()</code> to be followed by a call to |
| * <code>start()</code> on the same <code>Manager</code> instance. |
| * </ul> |
| * |
| * @author Craig R. McClanahan |
| */ |
| public interface Manager { |
| |
| |
| // ------------------------------------------------------------- Properties |
| |
| |
| /** |
| * Return the Container with which this Manager is associated. |
| * |
| * @deprecated Use {@link #getContext()}. This method will be removed in |
| * Tomcat 9 onwards. |
| */ |
| @Deprecated |
| public Container getContainer(); |
| |
| |
| /** |
| * Set the Container with which this Manager is associated. |
| * |
| * @param container The newly associated Container |
| * |
| * @deprecated Use {@link #setContext(Context)}. This method will be removed in |
| * Tomcat 9 onwards. |
| */ |
| @Deprecated |
| public void setContainer(Container container); |
| |
| |
| /** |
| * Return the Context with which this Manager is associated. |
| */ |
| public Context getContext(); |
| |
| |
| /** |
| * Set the Context with which this Manager is associated. The Context must |
| * be set to a non-null value before the Manager is first used. Multiple |
| * calls to this method before first use are permitted. Once the Manager has |
| * been used, this method may not be used to change the Context (including |
| * setting a {@code null} value) that the Manager is associated with. |
| * |
| * @param context The newly associated Context |
| */ |
| public void setContext(Context context); |
| |
| |
| /** |
| * Return the distributable flag for the sessions supported by |
| * this Manager. |
| * |
| * @deprecated Ignored. {@link Context#getDistributable()} always takes |
| * precedence. Will be removed in Tomcat 8.5.x. |
| */ |
| @Deprecated |
| public boolean getDistributable(); |
| |
| |
| /** |
| * Set the distributable flag for the sessions supported by this |
| * Manager. If this flag is set, all user data objects added to |
| * sessions associated with this manager must implement Serializable. |
| * |
| * @param distributable The new distributable flag |
| * |
| * @deprecated Ignored. {@link Context#getDistributable()} always takes |
| * precedence. Will be removed in Tomcat 8.5.x. |
| */ |
| @Deprecated |
| public void setDistributable(boolean distributable); |
| |
| |
| /** |
| * Return the default maximum inactive interval (in seconds) |
| * for Sessions created by this Manager. |
| * |
| * @deprecated Ignored. {@link Context#getSessionTimeout()} always takes |
| * precedence. Will be removed in Tomcat 8.5.x. |
| */ |
| @Deprecated |
| public int getMaxInactiveInterval(); |
| |
| |
| /** |
| * Set the default maximum inactive interval (in seconds) |
| * for Sessions created by this Manager. |
| * |
| * @param interval The new default value |
| * |
| * @deprecated Ignored. {@link Context#getSessionTimeout()} always takes |
| * precedence. Will be removed in Tomcat 8.5.x. |
| */ |
| @Deprecated |
| public void setMaxInactiveInterval(int interval); |
| |
| |
| /** |
| * return the session id generator |
| */ |
| public SessionIdGenerator getSessionIdGenerator(); |
| |
| |
| /** |
| * Sets the session id generator |
| * |
| * @param sessionIdGenerator The session id generator |
| */ |
| public void setSessionIdGenerator(SessionIdGenerator sessionIdGenerator); |
| |
| |
| /** |
| * Gets the session id length (in bytes) of Sessions created by |
| * this Manager. |
| * |
| * @deprecated Use {@link SessionIdGenerator#getSessionIdLength()}. |
| * This method will be removed in Tomcat 9 onwards. |
| * |
| * @return The session id length |
| */ |
| @Deprecated |
| public int getSessionIdLength(); |
| |
| |
| /** |
| * Sets the session id length (in bytes) for Sessions created by this |
| * Manager. |
| * |
| * @deprecated Use {@link SessionIdGenerator#setSessionIdLength(int)}. |
| * This method will be removed in Tomcat 9 onwards. |
| * |
| * @param idLength The session id length |
| */ |
| @Deprecated |
| public void setSessionIdLength(int idLength); |
| |
| |
| /** |
| * Returns the total number of sessions created by this manager. |
| * |
| * @return Total number of sessions created by this manager. |
| */ |
| public long getSessionCounter(); |
| |
| |
| /** |
| * Sets the total number of sessions created by this manager. |
| * |
| * @param sessionCounter Total number of sessions created by this manager. |
| */ |
| public void setSessionCounter(long sessionCounter); |
| |
| |
| /** |
| * Gets the maximum number of sessions that have been active at the same |
| * time. |
| * |
| * @return Maximum number of sessions that have been active at the same |
| * time |
| */ |
| public int getMaxActive(); |
| |
| |
| /** |
| * (Re)sets the maximum number of sessions that have been active at the |
| * same time. |
| * |
| * @param maxActive Maximum number of sessions that have been active at |
| * the same time. |
| */ |
| public void setMaxActive(int maxActive); |
| |
| |
| /** |
| * Gets the number of currently active sessions. |
| * |
| * @return Number of currently active sessions |
| */ |
| public int getActiveSessions(); |
| |
| |
| /** |
| * Gets the number of sessions that have expired. |
| * |
| * @return Number of sessions that have expired |
| */ |
| public long getExpiredSessions(); |
| |
| |
| /** |
| * Sets the number of sessions that have expired. |
| * |
| * @param expiredSessions Number of sessions that have expired |
| */ |
| public void setExpiredSessions(long expiredSessions); |
| |
| |
| /** |
| * Gets the number of sessions that were not created because the maximum |
| * number of active sessions was reached. |
| * |
| * @return Number of rejected sessions |
| */ |
| public int getRejectedSessions(); |
| |
| |
| /** |
| * Gets the longest time (in seconds) that an expired session had been |
| * alive. |
| * |
| * @return Longest time (in seconds) that an expired session had been |
| * alive. |
| */ |
| public int getSessionMaxAliveTime(); |
| |
| |
| /** |
| * Sets the longest time (in seconds) that an expired session had been |
| * alive. |
| * |
| * @param sessionMaxAliveTime Longest time (in seconds) that an expired |
| * session had been alive. |
| */ |
| public void setSessionMaxAliveTime(int sessionMaxAliveTime); |
| |
| |
| /** |
| * Gets the average time (in seconds) that expired sessions had been |
| * alive. This may be based on sample data. |
| * |
| * @return Average time (in seconds) that expired sessions had been |
| * alive. |
| */ |
| public int getSessionAverageAliveTime(); |
| |
| |
| /** |
| * Gets the current rate of session creation (in session per minute). This |
| * may be based on sample data. |
| * |
| * @return The current rate (in sessions per minute) of session creation |
| */ |
| public int getSessionCreateRate(); |
| |
| |
| /** |
| * Gets the current rate of session expiration (in session per minute). This |
| * may be based on sample data |
| * |
| * @return The current rate (in sessions per minute) of session expiration |
| */ |
| public int getSessionExpireRate(); |
| // --------------------------------------------------------- Public Methods |
| |
| |
| /** |
| * Add this Session to the set of active Sessions for this Manager. |
| * |
| * @param session Session to be added |
| */ |
| public void add(Session session); |
| |
| |
| /** |
| * Add a property change listener to this component. |
| * |
| * @param listener The listener to add |
| */ |
| public void addPropertyChangeListener(PropertyChangeListener listener); |
| |
| |
| /** |
| * Change the session ID of the current session to a new randomly generated |
| * session ID. |
| * |
| * @param session The session to change the session ID for |
| */ |
| public void changeSessionId(Session session); |
| |
| |
| /** |
| * Change the session ID of the current session to a specified session ID. |
| * |
| * @param session The session to change the session ID for |
| * @param newId new session ID |
| */ |
| public void changeSessionId(Session session, String newId); |
| |
| |
| /** |
| * Get a session from the recycled ones or create a new empty one. |
| * The PersistentManager manager does not need to create session data |
| * because it reads it from the Store. |
| */ |
| public Session createEmptySession(); |
| |
| |
| /** |
| * Construct and return a new session object, based on the default |
| * settings specified by this Manager's properties. The session |
| * id specified will be used as the session id. |
| * If a new session cannot be created for any reason, return |
| * <code>null</code>. |
| * |
| * @param sessionId The session id which should be used to create the |
| * new session; if <code>null</code>, the session |
| * id will be assigned by this method, and available via the getId() |
| * method of the returned session. |
| * @exception IllegalStateException if a new session cannot be |
| * instantiated for any reason |
| */ |
| public Session createSession(String sessionId); |
| |
| |
| /** |
| * Return the active Session, associated with this Manager, with the |
| * specified session id (if any); otherwise return <code>null</code>. |
| * |
| * @param id The session id for the session to be returned |
| * |
| * @exception IllegalStateException if a new session cannot be |
| * instantiated for any reason |
| * @exception IOException if an input/output error occurs while |
| * processing this request |
| */ |
| public Session findSession(String id) throws IOException; |
| |
| |
| /** |
| * Return the set of active Sessions associated with this Manager. |
| * If this Manager has no active Sessions, a zero-length array is returned. |
| */ |
| public Session[] findSessions(); |
| |
| |
| /** |
| * Load any currently active sessions that were previously unloaded |
| * to the appropriate persistence mechanism, if any. If persistence is not |
| * supported, this method returns without doing anything. |
| * |
| * @exception ClassNotFoundException if a serialized class cannot be |
| * found during the reload |
| * @exception IOException if an input/output error occurs |
| */ |
| public void load() throws ClassNotFoundException, IOException; |
| |
| |
| /** |
| * Remove this Session from the active Sessions for this Manager. |
| * |
| * @param session Session to be removed |
| */ |
| public void remove(Session session); |
| |
| |
| /** |
| * Remove this Session from the active Sessions for this Manager. |
| * |
| * @param session Session to be removed |
| * @param update Should the expiration statistics be updated |
| */ |
| public void remove(Session session, boolean update); |
| |
| |
| /** |
| * Remove a property change listener from this component. |
| * |
| * @param listener The listener to remove |
| */ |
| public void removePropertyChangeListener(PropertyChangeListener listener); |
| |
| |
| /** |
| * Save any currently active sessions in the appropriate persistence |
| * mechanism, if any. If persistence is not supported, this method |
| * returns without doing anything. |
| * |
| * @exception IOException if an input/output error occurs |
| */ |
| public void unload() throws IOException; |
| |
| /** |
| * This method will be invoked by the context/container on a periodic |
| * basis and allows the manager to implement |
| * a method that executes periodic tasks, such as expiring sessions etc. |
| */ |
| public void backgroundProcess(); |
| |
| |
| |
| /** |
| * Would the Manager distribute the given session attribute? Manager |
| * implementations may provide additional configuration options to control |
| * which attributes are distributable. |
| * |
| * @param name The attribute name |
| * @param value The attribute value |
| * |
| * @return {@code true} if the Manager would distribute the given attribute |
| * otherwise {@code false} |
| */ |
| public boolean willAttributeDistribute(String name, Object value); |
| } |
