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