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 }