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    }