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    package org.apache.geronimo.kernel.config;
018    
019    import org.apache.geronimo.kernel.repository.Artifact;
020    
021    /**
022     * This interface can be used to monitor the progress of an operation on the
023     * configuration manager.  Typically, the monitor will receive a number of
024     * calls to addConfiguration as the configuration manager decides which
025     * configurations will be effected by the operations.  This is followed by a
026     * call to loading, starting, stopping or unloading and then a call to
027     * succeeded or failed for each configuration added.
028     *
029     *
030     * The one notable exception to this is the load operation which calls
031     * addConfiguration and and immediately follows it with a reading and then
032     * succeeded or failed.  This is because the load operation needs to read each
033     * configuration to determine which additional configurations will need to be
034     * loaded.
035     *
036     * When an operation fails, the failed method is called with the cause.  The
037     * configuration manager normally will follow the failure with compensating
038     * actions to bring the server back to the original state.  For example, if it
039     * loaded a configuration, it will unload it.  Each of the compensating
040     * actions will cause events to be fired.
041     *
042     * When the, operation is completed, the finished method will be called.  This
043     *  should be called event if the operation ultimately fails and throws an
044     * exception.  It is recommended that you do not rely the finished method to
045     * be called in the case of an Exception as there are cases that will cause
046     * the configuration manager to immediately return without notification (such
047     * as an AssertionError).
048     * @version $Rev: 476049 $ $Date: 2006-11-16 23:35:17 -0500 (Thu, 16 Nov 2006) $
049     */
050    public interface LifecycleMonitor {
051        /**
052         * Adds a configuration to be monitored.
053         * @param configurationId the configuration identifier
054         */
055        void addConfiguration(Artifact configurationId);
056    
057        /**
058         * The configuration manager has started reading the specified configuration.
059         * @param configurationId the configuration identifier
060         */
061        void reading(Artifact configurationId);
062    
063        /**
064         * The configuration manager has begun loading the specified configuration.
065         * @param configurationId the configuration identifier
066         */
067        void loading(Artifact configurationId);
068    
069        /**
070         * The configuration manager has begun starting the specified configuration.
071         * @param configurationId the configuration identifier
072         */
073        void starting(Artifact configurationId);
074    
075        /**
076         * The configuration manager has begun stopping the specified configuration.
077         * @param configurationId the configuration identifier
078         */
079        void stopping(Artifact configurationId);
080    
081        /**
082         * The configuration manager has begun unloading the specified configuration.
083         * @param configurationId the configuration identifier
084         */
085        void unloading(Artifact configurationId);
086    
087        /**
088         * The previous operation on the specified configuration has completed successfully.
089         * @param configurationId the configuration identifier
090         */
091        void succeeded(Artifact configurationId);
092    
093        /**
094         * The previous operation on the specified configuration has failed due to the specified exception.
095         * @param configurationId the configuration identifier
096         */
097        void failed(Artifact configurationId, Throwable cause);
098    
099        /**
100         * The operation on the configuration manager has finished.
101         */
102        void finished();
103    }
104