Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    * 
    9    *      http://www.apache.org/licenses/LICENSE-2.0
   10    * 
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   
   18   
   19   package org.apache.catalina;
   20   
   21   
   22   import java.beans.PropertyChangeListener;
   23   import java.io.IOException;
   24   
   25   
   26   /**
   27    * A <b>Manager</b> manages the pool of Sessions that are associated with a
   28    * particular Container.  Different Manager implementations may support
   29    * value-added features such as the persistent storage of session data,
   30    * as well as migrating sessions for distributable web applications.
   31    * <p>
   32    * In order for a <code>Manager</code> implementation to successfully operate
   33    * with a <code>Context</code> implementation that implements reloading, it
   34    * must obey the following constraints:
   35    * <ul>
   36    * <li>Must implement <code>Lifecycle</code> so that the Context can indicate
   37    *     that a restart is required.
   38    * <li>Must allow a call to <code>stop()</code> to be followed by a call to
   39    *     <code>start()</code> on the same <code>Manager</code> instance.
   40    * </ul>
   41    *
   42    * @author Craig R. McClanahan
   43    * @version $Revision: 892545 $ $Date: 2009-12-20 02:04:17 +0100 (Sun, 20 Dec 2009) $
   44    */
   45   
   46   public interface Manager {
   47   
   48   
   49       // ------------------------------------------------------------- Properties
   50   
   51   
   52       /**
   53        * Return the Container with which this Manager is associated.
   54        */
   55       public Container getContainer();
   56   
   57   
   58       /**
   59        * Set the Container with which this Manager is associated.
   60        *
   61        * @param container The newly associated Container
   62        */
   63       public void setContainer(Container container);
   64   
   65   
   66       /**
   67        * Return the distributable flag for the sessions supported by
   68        * this Manager.
   69        */
   70       public boolean getDistributable();
   71   
   72   
   73       /**
   74        * Set the distributable flag for the sessions supported by this
   75        * Manager.  If this flag is set, all user data objects added to
   76        * sessions associated with this manager must implement Serializable.
   77        *
   78        * @param distributable The new distributable flag
   79        */
   80       public void setDistributable(boolean distributable);
   81   
   82   
   83       /**
   84        * Return descriptive information about this Manager implementation and
   85        * the corresponding version number, in the format
   86        * <code>&lt;description&gt;/&lt;version&gt;</code>.
   87        */
   88       public String getInfo();
   89   
   90   
   91       /**
   92        * Return the default maximum inactive interval (in seconds)
   93        * for Sessions created by this Manager.
   94        */
   95       public int getMaxInactiveInterval();
   96   
   97   
   98       /**
   99        * 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       /**
  108        * Gets the session id length (in bytes) of Sessions created by
  109        * this Manager.
  110        *
  111        * @return The session id length
  112        */
  113       public int getSessionIdLength();
  114   
  115   
  116       /**
  117        * Sets the session id length (in bytes) for Sessions created by this
  118        * Manager.
  119        *
  120        * @param idLength The session id length
  121        */
  122       public void setSessionIdLength(int idLength);
  123   
  124   
  125       /** 
  126        * Returns the total number of sessions created by this manager.
  127        *
  128        * @return Total number of sessions created by this manager.
  129        */
  130       public int getSessionCounter();
  131   
  132   
  133       /** 
  134        * Sets the total number of sessions created by this manager.
  135        *
  136        * @param sessionCounter Total number of sessions created by this manager.
  137        */
  138       public void setSessionCounter(int sessionCounter);
  139   
  140   
  141       /**
  142        * Gets the maximum number of sessions that have been active at the same
  143        * time.
  144        *
  145        * @return Maximum number of sessions that have been active at the same
  146        * time
  147        */
  148       public int getMaxActive();
  149   
  150   
  151       /**
  152        * (Re)sets the maximum number of sessions that have been active at the
  153        * same time.
  154        *
  155        * @param maxActive Maximum number of sessions that have been active at
  156        * the same time.
  157        */
  158       public void setMaxActive(int maxActive);
  159   
  160   
  161       /** 
  162        * Gets the number of currently active sessions.
  163        *
  164        * @return Number of currently active sessions
  165        */
  166       public int getActiveSessions();
  167   
  168   
  169       /**
  170        * Gets the number of sessions that have expired.
  171        *
  172        * @return Number of sessions that have expired
  173        */
  174       public int getExpiredSessions();
  175   
  176   
  177       /**
  178        * Sets the number of sessions that have expired.
  179        *
  180        * @param expiredSessions Number of sessions that have expired
  181        */
  182       public void setExpiredSessions(int expiredSessions);
  183   
  184   
  185       /**
  186        * Gets the number of sessions that were not created because the maximum
  187        * number of active sessions was reached.
  188        *
  189        * @return Number of rejected sessions
  190        */
  191       public int getRejectedSessions();
  192   
  193   
  194       /**
  195        * Sets the number of sessions that were not created because the maximum
  196        * number of active sessions was reached.
  197        *
  198        * @param rejectedSessions Number of rejected sessions
  199        */
  200       public void setRejectedSessions(int rejectedSessions);
  201   
  202   
  203       /**
  204        * Gets the longest time (in seconds) that an expired session had been
  205        * alive.
  206        *
  207        * @return Longest time (in seconds) that an expired session had been
  208        * alive.
  209        */
  210       public int getSessionMaxAliveTime();
  211   
  212   
  213       /**
  214        * Sets the longest time (in seconds) that an expired session had been
  215        * alive.
  216        *
  217        * @param sessionMaxAliveTime Longest time (in seconds) that an expired
  218        * session had been alive.
  219        */
  220       public void setSessionMaxAliveTime(int sessionMaxAliveTime);
  221   
  222   
  223       /**
  224        * Gets the average time (in seconds) that expired sessions had been
  225        * alive.
  226        *
  227        * @return Average time (in seconds) that expired sessions had been
  228        * alive.
  229        */
  230       public int getSessionAverageAliveTime();
  231   
  232   
  233       /**
  234        * Sets the average time (in seconds) that expired sessions had been
  235        * alive.
  236        *
  237        * @param sessionAverageAliveTime Average time (in seconds) that expired
  238        * sessions had been alive.
  239        */
  240       public void setSessionAverageAliveTime(int sessionAverageAliveTime);
  241   
  242   
  243       // --------------------------------------------------------- Public Methods
  244   
  245   
  246       /**
  247        * Add this Session to the set of active Sessions for this Manager.
  248        *
  249        * @param session Session to be added
  250        */
  251       public void add(Session session);
  252   
  253   
  254       /**
  255        * Add a property change listener to this component.
  256        *
  257        * @param listener The listener to add
  258        */
  259       public void addPropertyChangeListener(PropertyChangeListener listener);
  260   
  261   
  262       /**
  263        * Change the session ID of the current session to a new randomly generated
  264        * session ID.
  265        * 
  266        * @param session   The session to change the session ID for
  267        */
  268       public void changeSessionId(Session session);
  269       
  270       
  271       /**
  272        * Get a session from the recycled ones or create a new empty one.
  273        * The PersistentManager manager does not need to create session data
  274        * because it reads it from the Store.
  275        */                                                                         
  276       public Session createEmptySession();
  277   
  278   
  279       /**
  280        * Construct and return a new session object, based on the default
  281        * settings specified by this Manager's properties.  The session
  282        * id will be assigned by this method, and available via the getId()
  283        * method of the returned session.  If a new session cannot be created
  284        * for any reason, return <code>null</code>.
  285        * 
  286        * @exception IllegalStateException if a new session cannot be
  287        *  instantiated for any reason
  288        * @deprecated
  289        */
  290       public Session createSession();
  291   
  292   
  293       /**
  294        * Construct and return a new session object, based on the default
  295        * settings specified by this Manager's properties.  The session
  296        * id specified will be used as the session id.
  297        * If a new session cannot be created for any reason, return 
  298        * <code>null</code>.
  299        * 
  300        * @param sessionId The session id which should be used to create the
  301        *  new session; if <code>null</code>, the session
  302        *  id will be assigned by this method, and available via the getId()
  303        *  method of the returned session.
  304        * @exception IllegalStateException if a new session cannot be
  305        *  instantiated for any reason
  306        */
  307       public Session createSession(String sessionId);
  308   
  309   
  310       /**
  311        * Return the active Session, associated with this Manager, with the
  312        * specified session id (if any); otherwise return <code>null</code>.
  313        *
  314        * @param id The session id for the session to be returned
  315        *
  316        * @exception IllegalStateException if a new session cannot be
  317        *  instantiated for any reason
  318        * @exception IOException if an input/output error occurs while
  319        *  processing this request
  320        */
  321       public Session findSession(String id) throws IOException;
  322   
  323   
  324       /**
  325        * Return the set of active Sessions associated with this Manager.
  326        * If this Manager has no active Sessions, a zero-length array is returned.
  327        */
  328       public Session[] findSessions();
  329   
  330   
  331       /**
  332        * Load any currently active sessions that were previously unloaded
  333        * to the appropriate persistence mechanism, if any.  If persistence is not
  334        * supported, this method returns without doing anything.
  335        *
  336        * @exception ClassNotFoundException if a serialized class cannot be
  337        *  found during the reload
  338        * @exception IOException if an input/output error occurs
  339        */
  340       public void load() throws ClassNotFoundException, IOException;
  341   
  342   
  343       /**
  344        * Remove this Session from the active Sessions for this Manager.
  345        *
  346        * @param session Session to be removed
  347        */
  348       public void remove(Session session);
  349   
  350   
  351       /**
  352        * Remove a property change listener from this component.
  353        *
  354        * @param listener The listener to remove
  355        */
  356       public void removePropertyChangeListener(PropertyChangeListener listener);
  357   
  358   
  359       /**
  360        * Save any currently active sessions in the appropriate persistence
  361        * mechanism, if any.  If persistence is not supported, this method
  362        * returns without doing anything.
  363        *
  364        * @exception IOException if an input/output error occurs
  365        */
  366       public void unload() throws IOException;
  367       
  368        /**
  369         * This method will be invoked by the context/container on a periodic
  370         * basis and allows the manager to implement
  371         * a method that executes periodic tasks, such as expiring sessions etc.
  372         */
  373        public void backgroundProcess();
  374   
  375   }

Home » apache-tomcat-6.0.26-src » org.apache » catalina » [javadoc | source]