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: * @(#)Bootstrap.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:
033: import javax.management.ObjectName;
034:
035: /**
036: * This interface is implemented by a JBI Component to provide any special
037: * processing required at install/uninstall time. The methods defined here are
038: * called by the JBI implementation during the installation (or uninstallation)
039: * of the component that, among other things, supplies an implementation of this
040: * interface.
041: * <p>
042: * Initialization/cleanup tasks such as creation/deletion of directories, files,
043: * and database tables can be done by the {@link #onInstall()} and {@link
044: * #onUninstall()} methods, respectively. This also allows the component to
045: * terminate the installation or uninstallation in the event of an error.
046: * <p>
047: * After calling {@link #onInstall()} or {@link #onUninstall()}, regardless of
048: * outcome, the JBI implementation must call the {@link #cleanUp()} method
049: * afterwards. Similarly, if {@link #init(InstallationContext)} fails with
050: * an exception, the JBI implementation must call the {@link #cleanUp()} method.
051: * <p>
052: * Component implementors should note that there is no guarantee that
053: * the same instance of its <code>Bootstrap</code> implementation will be used
054: * during both install and uninstall operations on the component. Data that
055: * need to be retained between installation-time and uninstallation-time
056: * must be persisted in such as fashion that a separate instance of the
057: * bootstrap class can find them, despite component or system shutdown.
058: *
059: * @author JSR208 Expert Group
060: */
061: public interface Bootstrap {
062: /**
063: * Initializes the installation environment for a component. This method is
064: * expected to save any information from the installation context that
065: * may be needed by other methods.
066: * <p>
067: * If the component needs to register an optional installer configuration
068: * MBean, it MUST do so during execution of this method, or the
069: * getExtensionMBean() method.
070: * <p>
071: * This method must be called after the installation root (available
072: * through the installContext parameter) is prepared.
073: *
074: * @param installContext the context containing information from the
075: * install command and from the component installation
076: * ZIP file; this must be non-null.
077: * @exception JBIException when there is an error requiring that
078: * the installation be terminated
079: */
080: void init(InstallationContext installContext) throws JBIException;
081:
082: /**
083: * Cleans up any resources allocated by the bootstrap implementation,
084: * including performing deregistration of the extension MBean, if
085: * applicable.
086: * <p>
087: * This method must be called after the onInstall() or onUninstall() method
088: * is called, whether it succeeds or fails. It must be called after
089: * init() is called, if init() fails by throwing an exception.
090: *
091: * @exception JBIException if the bootstrap cannot clean up allocated
092: * resources
093: */
094: void cleanUp() throws JBIException;
095:
096: /**
097: * Obtains the <code>ObjectName</code> of the optional installer
098: * configuration MBean. If none is provided by this component, this method
099: * must return <code>null</code>.
100: * <p>
101: * This method must be called before onInstall() (or onUninstall()) is
102: * called by the JBI implementation.
103: *
104: * @return ObjectName of the optional installer configuration MBean;
105: * returns <code>null</code> if there is no such MBean
106: */
107: ObjectName getExtensionMBeanName();
108:
109: /**
110: * Called at the beginning of installation of a component to perform any
111: * special installation tasks required by the component.
112: * <p>
113: * This method must not be called if the init() method failed with an
114: * exception.
115: *
116: * @exception JBIException when there is an error requiring that
117: * the installation be terminated
118: */
119: void onInstall() throws JBIException;
120:
121: /**
122: * Called at the beginning of uninstallation of a component to perform any
123: * special uninstallation tasks required by the component.
124: * <p>
125: * This method must not be called if the init() method failed with an
126: * exception.
127: *
128: * @exception JBIException when there is an error requiring that
129: * the uninstallation be terminated.
130: */
131: void onUninstall() throws JBIException;
132: }
|