001: /*
002: * BEGIN_HEADER - DO NOT EDIT
003: *
004: * The contents of this file are subject to the terms
005: * of the Common Development and Distribution License
006: * (the "License"). You may not use this file except
007: * in compliance with the License.
008: *
009: * You can obtain a copy of the license at
010: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
011: * See the License for the specific language governing
012: * permissions and limitations under the License.
013: *
014: * When distributing Covered Code, include this CDDL
015: * HEADER in each file and include the License file at
016: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
017: * If applicable add the following below this CDDL HEADER,
018: * with the fields enclosed by brackets "[]" replaced with
019: * your own identifying information: Portions Copyright
020: * [year] [name of copyright owner]
021: */
022:
023: /*
024: * @(#)ComponentLifeCycle.java
025: * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
026: *
027: * END_HEADER - DO NOT EDIT
028: */
029: package javax.jbi.component;
030:
031: import javax.jbi.JBIException;
032: import javax.jbi.component.ComponentContext;
033:
034: import javax.management.ObjectName;
035:
036: /**
037: * This interface must be implemented by a JBI component to provide
038: * initialization, start, stop, and shutdown life cycle processing. These
039: * methods comprise the life cycle contract between the JBI implementation and
040: * the component. The life cycle of a component begins with a call to the init()
041: * method on an instance of the component's implementation of this interface,
042: * and ends with the first call to the shutDown() method on that instance.
043: * Between these two calls, there can be any number of stop() and start() calls.
044: * <p>
045: * The JBI implementation must track the running state of a component, and
046: * ensure that life cycle state changes are always legal. For example, if
047: * the management interface for controlling a component's life cycle
048: * ({@link javax.jbi.management.ComponentLifeCycleMBean}) is used to start
049: * a component that was just installed (and thus in the <i>Shutdown</i> state),
050: * the implementation must invoke this component's
051: * {@link #init(ComponentContext)} method before invoking its
052: * {@link #start()} method.
053: *
054: * @author JSR208 Expert Group
055: */
056: public interface ComponentLifeCycle {
057: /**
058: * Get the JMX object name for the extension MBean for this component; if
059: * there is none, return <code>null</code>.
060: *
061: * @return the JMX object name of the additional MBean or <code>null</code>
062: * if there is no additional MBean.
063: */
064: ObjectName getExtensionMBeanName();
065:
066: /**
067: * Initialize the component. This performs initialization required by the
068: * component but does not make it ready to process messages. This method is
069: * called once for each life cycle of the component.
070: * <p>
071: * If the component needs to register an additional MBean to extend its
072: * life cycle, or provide other component management tasks, it should
073: * be registered during this call.
074: *
075: * @param context the component's context, providing access to component
076: * data provided by the JBI environment; must be non-null.
077: * @exception JBIException if the component is unable to initialize.
078: */
079: void init(ComponentContext context) throws JBIException;
080:
081: /**
082: * Shut down the component. This performs clean-up, releasing all run-time
083: * resources used by the component. Once this method has been called,
084: * {@link #init(ComponentContext)} must be called before the component can
085: * be started again with a call to {@link #start()}.
086: *
087: * @exception JBIException if the component is unable to shut down.
088: */
089: void shutDown() throws JBIException;
090:
091: /**
092: * Start the component. This makes the component ready to process messages.
093: * This method is called after {@link #init(ComponentContext)}, both when
094: * the component is being started for the first time and when the component
095: * is being restarted after a previous call to {@link #shutDown()}.
096: * If {@link #stop()} was called previously but {@link #shutDown()} was not,
097: * <code>start()</code> can be called again without another call to
098: * {@link #init(ComponentContext)}.
099: *
100: * @exception JBIException if the component is unable to start.
101: */
102: void start() throws JBIException;
103:
104: /**
105: * Stop the component. This makes the component stop accepting messages for
106: * processing. After a call to this method, {@link #start()} may be called
107: * again without first calling {@link #init(ComponentContext)}.
108: *
109: * @exception JBIException if the component is unable to stop.
110: */
111: void stop() throws JBIException;
112: }
|