com.sun.jbi

Interface ComponentManager

public interface ComponentManager

This is the public interface to the Component Framework, which provides installation and management of Binding Components, Service Engines, and and Shared Libraries within the JBI environment.

Author:

Sun Microsystems, Inc.

Method Summary

Methods

Modifier and Type	Method and Description
void	cancelComponentUpgrade(String componentName) Cancel a pending component upgrade.
Component	getComponentInstance(String componentName) Get the javax.jbi.component.Component instance for the component with the specified name.
DeployerMBean	getDeployerInstance(String componentName) Get the com.sun.jbi.framework.DeployerMBean instance for the component with the specified name.
void	installSharedLibrary(String name, String description, String componentRoot, boolean isSelfFirst, List elements) Install a Shared Library into the JBI framework.
ObjectName	loadBootstrap(InstallationContext installContext, String bootClassName, List bootClassPathElements, List sharedLibraryList, boolean force) Load a component's bootstrap into the JBI framework.
void	uninstallSharedLibrary(String id) Uninstall a Shared Library from the JBI framework.
void	unloadBootstrap(String componentName) Unload a component's bootstrap from the JBI framework.
void	upgradeComponent(InstallationContext installContext, String bootClassName, List<String> bootClassPathElements, List<String> sharedLibraryList) Upgrade an installed component.
boolean	validateComponentForUpgrade(InstallationContext installContext, String bootClassName, List<String> bootClassPathElements, List<String> sharedLibraryList) Validate a component for upgrade.

Method Detail

getComponentInstance

Component getComponentInstance(String componentName)

Get the javax.jbi.component.Component instance for the component with the specified name. If no instance exists, returns null.

Parameters:

componentName - The unique name of the component.

Returns:

The instance of javax.jbi.component.Component or null if none is found.

getDeployerInstance

DeployerMBean getDeployerInstance(String componentName)

Get the com.sun.jbi.framework.DeployerMBean instance for the component with the specified name. If no instance exists, returns null.

Parameters:

componentName - The unique name of the component.

Returns:

The instance of com.sun.jbi.framework.DeployerMBean or null if none is found.

installSharedLibrary

void installSharedLibrary(String name,
                        String description,
                        String componentRoot,
                        boolean isSelfFirst,
                        List elements)
                          throws JBIException

Install a Shared Library into the JBI framework.

Parameters:

name - The unique name of the Shared Library.

description - The description of the Shared Library.

componentRoot - The root directory for this Shared Library.

isSelfFirst - Set to true to force the class loader for this Shared Library to use a self-first hierarchy, or false for parent-first.

elements - The list of jar files and class directories included in this Shared Library, as a List of String objects in the order in which they should appear in the class path. Each list element contains the full path to either a jar file or a directory containing class files.

Throws:

JBIException - if any error occurs.

loadBootstrap

ObjectName loadBootstrap(InstallationContext installContext,
                       String bootClassName,
                       List bootClassPathElements,
                       List sharedLibraryList,
                       boolean force)
                         throws JBIException

Load a component's bootstrap into the JBI framework. This is the first step in the installation and uninstallation processes. It creates and registers the InstallerMBean that is used to complete the installation or uninstallation.

Parameters:

installContext - The installation context.

bootClassName - The name of the bootstrap class for the component.

bootClassPathElements - A list of elements comprising the class path for loading the bootstrap class. Each element in the list is a String containing the full path to either a jar file or a directory containing class files.

sharedLibraryList - A list of String objects specifing the names of the Shared Libraries required by the component, in the order in which they should appear in the class path.

force - Set to true if this is for a forced uninstall.

Returns:

The JMX object name of the installation configuration MBean provided by the component, if any is provided, or null otherwise.

Throws:

JBIException - if the bootstrap cannot be loaded.

uninstallSharedLibrary

void uninstallSharedLibrary(String id)
                            throws JBIException

Uninstall a Shared Library from the JBI framework. A Shared Library cannot be uninstalled until all dependent components (BCs and SEs) have been shut down. If any active dependent components are found, the uninstall of the Shared Library is aborted.

Parameters:

id - The component ID of the Shared Library.

Throws:

JBIException - if the uninstall fails.

unloadBootstrap

void unloadBootstrap(String componentName)
                     throws JBIException

Unload a component's bootstrap from the JBI framework. This is the last step in the installation and uninstallation processes. It unregisters the InstallerMBean that was used to complete the installation or uninstallation, and calls the bootstrap cleanUp() method if it has not yet been called. Note that in the case where the this method is called after loadBootstrap() for a new component, without an intervening call to installComponent(), the Component instance is removed here.

Parameters:

componentName - The unique name of the component.

Throws:

JBIException - if the bootstrap cannot be unloaded.

cancelComponentUpgrade

void cancelComponentUpgrade(String componentName)
                            throws JBIException

Cancel a pending component upgrade. This is called when some failure has occurred after validateComponentForUpgrade() has already been called but before upgradeComponent() is called. All this method does is return the component to the SHUTDOWN state and remove the busy indicator from the component entry in the runtime registry cache.

Parameters:

componentName - The name of the component.

Throws:

JBIException - if the component does not exist.

upgradeComponent

void upgradeComponent(InstallationContext installContext,
                    String bootClassName,
                    List<String> bootClassPathElements,
                    List<String> sharedLibraryList)
                      throws JBIException

Upgrade an installed component. This is used to upgrade a component to a newer version without requiring the component to be uninstalled (which requires undeployment of all Service Assemblies that have Service Units deployed to the component). There are two ways a component can be updated. If the component does not provide an upgrade() method in its bootstrap class, then the runtime jar files are updated and any changes to the component's installation descriptor in jbi.xml are propagated. If the component provides an upgrade() method, that method is called to give the component the opportunity to upgrade its workspace and all SUs deployed to it to a new version. In this case, it is the responsibility of the component to perform all version verification, and to provide any recovery processing required in the event of a failed upgrade.

Parameters:

installContext - The installation context.

bootClassName - The name of the component's bootstrap class.

bootClassPathElements - A list of elements comprising the class path for loading the bootstrap class. Each element in the list is a String containing the full path to either a jar file or a directory containing class files.

sharedLibraryList - A list of String objects specifing the names of the Shared Libraries required by the component, in the order in which they should appear in the class path.

Throws:

JBIException - if the update fails for some reason.

validateComponentForUpgrade

boolean validateComponentForUpgrade(InstallationContext installContext,
                                  String bootClassName,
                                  List<String> bootClassPathElements,
                                  List<String> sharedLibraryList)
                                    throws JBIException

Validate a component for upgrade. This validates that the runtime jar files provided for the upgrade contain valid implementations of the required interfaces and the component classes will load correctly. It also verifies that all Shared Library dependencies are met. Finally, it determines whether or not the component has provided an implementation of the upgrade() method and returns an indicator of that to the caller.

Parameters:

installContext - The installation context.

bootClassName - The name of the bootstrap class for the component.

bootClassPathElements - A list of elements comprising the class path for loading the bootstrap class. Each element in the list is a String containing the full path to either a jar file or a directory containing class files.

sharedLibraryList - A list of String objects specifing the names of the Shared Libraries required by the component, in the order in which they should appear in the class path.

Returns:

true if the component provided an upgrade() method, false if not.

Throws:

JBIException - if there is a problem with the component implementation classes or with Shared Library dependencies.