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: * @(#)ComponentManager.java
025: * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
026: *
027: * END_HEADER - DO NOT EDIT
028: */
029: package com.sun.jbi;
030:
031: import java.util.List;
032:
033: import javax.management.ObjectName;
034:
035: /**
036: * This is the public interface to the Component Framework, which provides
037: * installation and management of Binding Components, Service Engines, and
038: * and Shared Libraries within the JBI environment.
039: *
040: * @author Sun Microsystems, Inc.
041: */
042: public interface ComponentManager {
043: /**
044: * Get the javax.jbi.component.Component instance for the component with
045: * the specified name. If no instance exists, returns null.
046: * @param componentName The unique name of the component.
047: * @return The instance of javax.jbi.component.Component or null if none
048: * is found.
049: */
050: javax.jbi.component.Component getComponentInstance(
051: String componentName);
052:
053: /**
054: * Get the com.sun.jbi.framework.DeployerMBean instance for the component
055: * with the specified name. If no instance exists, returns null.
056: * @param componentName The unique name of the component.
057: * @return The instance of com.sun.jbi.framework.DeployerMBean or null if
058: * none is found.
059: */
060: com.sun.jbi.framework.DeployerMBean getDeployerInstance(
061: String componentName);
062:
063: /**
064: * Install a Shared Library into the JBI framework.
065: * @param name The unique name of the Shared Library.
066: * @param description The description of the Shared Library.
067: * @param componentRoot The root directory for this Shared Library.
068: * @param isSelfFirst Set to true to force the class loader for this Shared
069: * Library to use a self-first hierarchy, or false for parent-first.
070: * @param elements The list of jar files and class directories included in
071: * this Shared Library, as a List of String objects in the order in which
072: * they should appear in the class path. Each list element contains the full
073: * path to either a jar file or a directory containing class files.
074: * @throws javax.jbi.JBIException if any error occurs.
075: */
076: void installSharedLibrary(String name, String description,
077: String componentRoot, boolean isSelfFirst, List elements)
078: throws javax.jbi.JBIException;
079:
080: /**
081: * Load a component's bootstrap into the JBI framework. This is the first
082: * step in the installation and uninstallation processes. It creates and
083: * registers the InstallerMBean that is used to complete the installation
084: * or uninstallation.
085: * @param installContext The installation context.
086: * @param bootClassName The name of the bootstrap class for the component.
087: * @param bootClassPathElements A list of elements comprising the class
088: * path for loading the bootstrap class. Each element in the list is a
089: * String containing the full path to either a jar file or a directory
090: * containing class files.
091: * @param sharedLibraryList A list of String objects specifing the names of
092: * the Shared Libraries required by the component, in the order in which
093: * they should appear in the class path.
094: * @return The JMX object name of the installation configuration MBean
095: * provided by the component, if any is provided, or null otherwise.
096: * @throws javax.jbi.JBIException if the bootstrap cannot be loaded.
097: */
098: ObjectName loadBootstrap(
099: com.sun.jbi.component.InstallationContext installContext,
100: String bootClassName, List bootClassPathElements,
101: List sharedLibraryList) throws javax.jbi.JBIException;
102:
103: /**
104: * Uninstall a Shared Library from the JBI framework. A Shared Library
105: * cannot be uninstalled until all dependent components (BCs and SEs) have
106: * been shut down. If any active dependent components are found, the
107: * uninstall of the Shared Library is aborted.
108: * @param id The component ID of the Shared Library.
109: * @throws javax.jbi.JBIException if the uninstall fails.
110: */
111: void uninstallSharedLibrary(String id)
112: throws javax.jbi.JBIException;
113:
114: /**
115: * Unload a component's bootstrap from the JBI framework. This is the last
116: * step in the installation and uninstallation processes. It unregisters
117: * the InstallerMBean that was used to complete the installation or
118: * uninstallation, and calls the bootstrap cleanUp() method if it has not
119: * yet been called. Note that in the case where the this method is called
120: * after loadBootstrap() for a new component, without an intervening call to
121: * installComponent(), the Component instance is removed here.
122: * @param componentName The unique name of the component.
123: * @throws javax.jbi.JBIException if the bootstrap cannot be unloaded.
124: */
125: void unloadBootstrap(String componentName)
126: throws javax.jbi.JBIException;
127:
128: /**
129: * Cancel a pending component upgrade. This is called when some failure
130: * has occurred after <code>validateComponentForUpgrade()</code> has already
131: * been called but before <code>upgradeComponent()</code> is called. All
132: * this method does is return the component to the <code>SHUTDOWN</code>
133: * state and remove the busy indicator from the component entry in the
134: * runtime registry cache.
135: * @param componentName The name of the component.
136: * @throws javax.jbi.JBIException if the component does not exist.
137: */
138: void cancelComponentUpgrade(String componentName)
139: throws javax.jbi.JBIException;
140:
141: /**
142: * Upgrade an installed component. This is used to upgrade a component to a
143: * newer version without requiring the component to be uninstalled (which
144: * requires undeployment of all Service Assemblies that have Service Units
145: * deployed to the component). There are two ways a component can be updated.
146: * If the component does not provide an <code>upgrade()</code> method in its
147: * bootstrap class, then the runtime jar files are updated and any changes
148: * to the component's installation descriptor in jbi.xml are propagated. If
149: * the component provides an <code>upgrade()</code> method, that method is
150: * called to give the component the opportunity to upgrade its workspace
151: * and all SUs deployed to it to a new version. In this case, it is the
152: * responsibility of the component to perform all version verification, and
153: * to provide any recovery processing required in the event of a failed
154: * upgrade.
155: *
156: * @param installContext The installation context.
157: * @param bootClassName The name of the component's bootstrap class.
158: * @param bootClassPathElements A list of elements comprising the class
159: * path for loading the bootstrap class. Each element in the list is a
160: * <code>String</code> containing the full path to either a jar file or a
161: * directory containing class files.
162: * @param sharedLibraryList A list of <code>String</code> objects specifing
163: * the names of the Shared Libraries required by the component, in the order
164: * in which they should appear in the class path.
165: * @throws javax.jbi.JBIException if the update fails for some reason.
166: */
167: void upgradeComponent(
168: com.sun.jbi.component.InstallationContext installContext,
169: String bootClassName, List<String> bootClassPathElements,
170: List<String> sharedLibraryList)
171: throws javax.jbi.JBIException;
172:
173: /**
174: * Validate a component for upgrade. This validates that the runtime jar
175: * files provided for the upgrade contain valid implementations of the
176: * required interfaces and the component classes will load correctly. It
177: * also verifies that all Shared Library dependencies are met. Finally, it
178: * determines whether or not the component has provided an implementation
179: * of the <code>upgrade()</code> method and returns an indicator of that to
180: * the caller.
181: *
182: * @param installContext The installation context.
183: * @param bootClassName The name of the bootstrap class for the component.
184: * @param bootClassPathElements A list of elements comprising the class
185: * path for loading the bootstrap class. Each element in the list is a
186: * <code>String</code> containing the full path to either a jar file or a
187: * directory containing class files.
188: * @param sharedLibraryList A list of <code>String</code> objects specifing
189: * the names of the Shared Libraries required by the component, in the order
190: * in which they should appear in the class path.
191: * @return <code>true</code> if the component provided an <code>upgrade()
192: * </code> method, <code>false</code> if not.
193: * @throws javax.jbi.JBIException if there is a problem with the component
194: * implementation classes or with Shared Library dependencies.
195: */
196: boolean validateComponentForUpgrade(
197: com.sun.jbi.component.InstallationContext installContext,
198: String bootClassName, List<String> bootClassPathElements,
199: List<String> sharedLibraryList)
200: throws javax.jbi.JBIException;
201: }
|