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