tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r919100 - in /tomcat/trunk/java/org/apache/catalina: Lifecycle.java LifecycleState.java
Date Thu, 04 Mar 2010 18:06:21 GMT
Author: markt
Date: Thu Mar  4 18:06:21 2010
New Revision: 919100

URL: http://svn.apache.org/viewvc?rev=919100&view=rev
Log:
Lifecycle refactoring.
Part 1 of many.
Better define the start and stop methods as well as the overall component lifecycle and the
relationship between start/stop, component state and events.
Add a getState() method but it is commented out in this checkin to prevent compilation errors.
It will be uncommented once the method has been added to the components that implement Lifecycle.

Added:
    tomcat/trunk/java/org/apache/catalina/LifecycleState.java
Modified:
    tomcat/trunk/java/org/apache/catalina/Lifecycle.java

Modified: tomcat/trunk/java/org/apache/catalina/Lifecycle.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/Lifecycle.java?rev=919100&r1=919099&r2=919100&view=diff
==============================================================================
--- tomcat/trunk/java/org/apache/catalina/Lifecycle.java (original)
+++ tomcat/trunk/java/org/apache/catalina/Lifecycle.java Thu Mar  4 18:06:21 2010
@@ -21,14 +21,52 @@
 
 /**
  * Common interface for component life cycle methods.  Catalina components
- * may, but are not required to, implement this interface (as well as the
- * appropriate interface(s) for the functionality they support) in order to
- * provide a consistent mechanism to start and stop the component.
+ * may implement this interface (as well as the appropriate interface(s) for
+ * the functionality they support) in order to provide a consistent mechanism
+ * to start and stop the component.
+ * <br>
+ * The valid state transitions for components that support Lifecycle are:
+ * <pre>
+ *                  --------------------<--------------------------
+ *                  |                                             |
+ *     start()      |        auto          auto         stop()    |       
+ * NEW --->--- STARTING_PREP -->- STARTING -->- STARTED -->---    |
+ *                                                 |         |    |
+ *                                     auto        |         |    |
+ *      ---------<----- MUST_STOP --<---------------         |    |
+ *      |                                                    |    |
+ *      ---------------------------<--------------------------    ^
+ *      |                                                         |
+ *      |        auto          auto                start()        |
+ * STOPPING_PREP -->- STOPPING -->- STOPPED -------------->--------
+ *      ^
+ *      |stop()
+ *      |
+ *   FAILED
+ * 
+ * Any state can transition to FAILED.
+ * 
+ * Calling start() while a component is in states STARTING_PREP, STARTING or
+ * STARTED has no effect.
+ * 
+ * Calling stop() while a component is in states STOPPING_PREP, STOPPING or
+ * STOPPED has no effect.
+ * 
+ * MUST_STOP is used to indicate that the {@link #stop()} should be called on
+ * the component as soon as {@link start()} exits.
+ * 
+ * Attempting any other transition will throw {@link LifecycleException}.
+ * 
+ * </pre>
+ * The {@link LifecycleEvent}s fired during state changes are defined in the
+ * methods that trigger the changed. No {@link LifecycleEvent}s are fired if the
+ * attempted transition is not valid.
+ * 
+ * TODO: Not all components may transition from STOPPED to STARTING_PREP
  *
  * @author Craig R. McClanahan
  * @version $Revision$ $Date$
  */
-
 public interface Lifecycle {
 
 
@@ -118,8 +156,21 @@
     /**
      * Prepare for the beginning of active use of the public methods of this
      * component.  This method should be called before any of the public
-     * methods of this component are utilized.  It should also send a
-     * LifecycleEvent of type START_EVENT to any registered listeners.
+     * methods of this component are utilized. The following
+     * {@link LifecycleEvent}s will be fired in the following order:
+     * <ol>
+     *   <li>BEFORE_START_EVENT: At the beginning of the method. It is as this
+     *                           point the state transitions to
+     *                           {@link LifecycleState#STARTING_PREP}.</li>
+     *   <li>START_EVENT: During the method once it is safe to call start() for
+     *                    any child components. It is at this point that the
+     *                    state transitions to {@link LifecycleState#STARTING}
+     *                    and that the public methods may be used.</li>
+     *   <li>AFTER_START_EVENT: At the end of the method, immediately before it
+     *                          returns. It is at this point that the state
+     *                          transitions to {@link LifecycleState#STARTED}.
+     *                          </li>
+     * </ol>
      *
      * @exception LifecycleException if this component detects a fatal error
      *  that prevents this component from being used
@@ -129,14 +180,35 @@
 
     /**
      * Gracefully terminate the active use of the public methods of this
-     * component.  This method should be the last one called on a given
-     * instance of this component.  It should also send a LifecycleEvent
-     * of type STOP_EVENT to any registered listeners.
-     *
+     * component. Once the STOP_EVENT is fired, the public methods should not
+     * be used. The following {@link LifecycleEvent}s will be fired in the
+     * following order:
+     * <ol>
+     *   <li>BEFORE_STOP_EVENT: At the beginning of the method. It is at this
+     *                          point that the state transitions to
+     *                          {@link LifecycleState#STOPPING_PREP}.</li>
+     *   <li>STOP_EVENT: During the method once it is safe to call stop() for
+     *                   any child components. It is at this point that the
+     *                   state transitions to {@link LifecycleState#STOPPING}
+     *                   and that the public methods may no longer be used.</li>
+     *   <li>AFTER_STOP_EVENT: At the end of the method, immediately before it
+     *                         returns. It is at this point that the state
+     *                         transitions to {@link LifecycleState#STOPPED}.
+     *                         </li>
+     * </ol>
+     * 
      * @exception LifecycleException if this component detects a fatal error
      *  that needs to be reported
      */
     public void stop() throws LifecycleException;
 
 
+    /**
+     * Obtain the current state of the source component.
+     * 
+     * @return The current state of the source component.
+     */
+    // TODO Remove this comment once all components that implement Lifecycle
+    //      have had this method added
+    //public LifecycleState getState();
 }

Added: tomcat/trunk/java/org/apache/catalina/LifecycleState.java
URL: http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/LifecycleState.java?rev=919100&view=auto
==============================================================================
--- tomcat/trunk/java/org/apache/catalina/LifecycleState.java (added)
+++ tomcat/trunk/java/org/apache/catalina/LifecycleState.java Thu Mar  4 18:06:21 2010
@@ -0,0 +1,56 @@
+/*
+ * 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;
+
+/**
+ * The list of valid states for components that implement {@link Lifecycle}.
+ * See {@link Lifecycle} for the state transition diagram.
+ */
+public enum LifecycleState {
+    NEW(false, null),
+    STARTING_PREP(false, Lifecycle.BEFORE_START_EVENT),
+    STARTING(true, Lifecycle.START_EVENT),
+    STARTED(true, Lifecycle.AFTER_START_EVENT),
+    STOPPING_PREP(true, Lifecycle.BEFORE_STOP_EVENT),
+    STOPPING(false, Lifecycle.STOP_EVENT),
+    STOPPED(false, Lifecycle.AFTER_STOP_EVENT),
+    FAILED(false, null),
+    MUST_STOP(true, null);
+    
+    private final boolean available;
+    private final String lifecycleEvent;
+    
+    private LifecycleState(boolean available, String lifecycleEvent) {
+        this.available = available;
+        this.lifecycleEvent = lifecycleEvent;
+    }
+    
+    /**
+     * Is a component in this state available for use?
+     */
+    public boolean isAvailable() {
+        return available;
+    }
+    
+    /**
+     * 
+     */
+    public String getLifecycleEvent() {
+        return lifecycleEvent;
+    }
+}



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message