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    }