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 javax.jbi.component; 018 019 import javax.jbi.JBIException; 020 import javax.management.ObjectName; 021 022 /** 023 * This interface must be implemented by a JBI component to provide initialization, 024 * start, stop, and shutdown life cycle processing. These methods comprise the life 025 * cycle contract between the JBI implementation and the component. The life cycle 026 * of a component begins with a call to the init() method on an instance of the 027 * component's implementation of this interface, and ends with the first call to the 028 * shutDown() method on that instance. Between these two calls, there can be any 029 * number of stop() and start() calls. 030 * 031 * The JBI implementation must track the running state of a component, and ensure 032 * that life cycle state changes are always legal. For example, if the management 033 * interface for controlling a component's life cycle ({@link 034 * javax.jbi.management.ComponentLifeCycleMBean}) is used to start a component that 035 * was just installed (and thus in the <i>Shutdown</i> state), the implementation 036 * must invoke this component's {@link #init(ComponentContext)} method before 037 * invoking its {@link #start()} method. 038 * 039 * @author JSR208 Expert Group 040 */ 041 public interface ComponentLifeCycle { 042 043 /** 044 * Get the JMX object name for the extension MBean for this component; if there 045 * is none, return null. 046 * 047 * @return the JMX object name of the additional MBean or null if there is no 048 * additional MBean. 049 */ 050 ObjectName getExtensionMBeanName(); 051 052 /** 053 * Initialize the component. This performs initialization required by the component 054 * but does not make it ready to process messages. This method is called once for 055 * each life cycle of the component. 056 * 057 * If the component needs to register an additional MBean to extend its life cycle, 058 * or provide other component management tasks, it should be registered during this 059 * call. 060 * 061 * @param context the component's context, providing access to component data provided 062 * by the JBI environment; must be non-null. 063 * @throws JBIException if the component is unable to initialize. 064 */ 065 void init(ComponentContext context) throws JBIException; 066 067 /** 068 * Shut down the component. This performs clean-up, releasing all run-time resources 069 * used by the component. Once this method has been called, {@link #init(ComponentContext)} 070 * must be called before the component can be started again with a call to {@link #start()}. 071 * 072 * @throws JBIException if the component is unable to shut down. 073 */ 074 void shutDown() throws JBIException; 075 076 /** 077 * Start the component. This makes the component ready to process messages. This method 078 * is called after {@link #init(ComponentContext)}, both when the component is being 079 * started for the first time and when the component is being restarted after a previous 080 * call to {@link #shutDown()}. If {@link #stop()} was called previously but {@link #shutDown()} 081 * was not, {@link #start()} can be called again without another call to 082 * {@link #init(ComponentContext)}. 083 * 084 * @throws JBIException if the component is unable to start. 085 */ 086 void start() throws JBIException; 087 088 /** 089 * Stop the component. This makes the component stop accepting messages for processing. 090 * After a call to this method, {@link #start()} may be called again without first 091 * calling {@link #init(ComponentContext)}. 092 * 093 * @throws JBIException if the component is unable to stop. 094 */ 095 void stop() throws JBIException; 096 }