javax.jbi.component.InstallationContext Maven / Gradle / Ivy
Show all versions of petals-jbi Show documentation
/**
* @(#) InstallationContext.java
*
* PETALS - PETALS Services Platform.
* Copyright (c) 2005 Fossil E-Commerce, http://www.fossilec.com/
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* -------------------------------------------------------------------------
* $Id: InstallationContext.java 217 2006-04-13 14:24:13Z alouis $
* -------------------------------------------------------------------------
*/
//
// This source code implements specifications defined by the Java
// Community Process. In order to remain compliant with the specification
// DO NOT add / change / or delete method signatures!
//
package javax.jbi.component;
/**
* This context contains information necessary for a JBI component to perform
* its installation/uninstallation processing. This is provided to the init()
* method of the component {@link Bootstrap} interface.
*
* @author JSR208 Expert Group
*/
public interface InstallationContext {
/**
* Get a list of elements that comprise the class path for this component.
* Each element represents either a directory (containing class files) or a
* jar file. All elements are reachable from the install root. These
* elements represent class path items that the component's execution-time
* component class loader uses, in search order. All path elements must use
* the file separator character appropriate to the system (i.e.,
* File.separator).
*
* @return a list of String objects, each of which contains a class path
* elements. The list must contain at least one class path element.
*/
public java.util.List getClassPathElements();
/**
* Get the name of the class that implements the {@link Component} interface
* for this component. This must be the component class name given in the
* component's installation descriptor.
*
* @return the {@link Component} implementation class name, which must be
* non-null and non-empty
*/
public java.lang.String getComponentClassName();
/**
* Get the unique name assigned to this component. This name must be
* assigned from the component's installation descriptor identification
* section.
*
* @return the unique component name, which must be non-null and non-empty.
*/
public java.lang.String getComponentName();
/**
* Get the JBI context for this component. The following methods are valid
* to use on the context:
*
* - {@link ComponentContext#getMBeanNames()}
*
- {@link ComponentContext#getMBeanServer()}
*
- {@link ComponentContext#getNamingContext()}
*
- {@link ComponentContext#getTransactionManager()}
*
*
* All other methods on the returned context must throw a
* IllegalStateException exception if invoked.
*
* @return the JBI context for this component, which must be non-null.
*/
public javax.jbi.component.ComponentContext getContext();
/**
* Return a DOM document fragment representing the installation descriptor
* (jbi.xml) extension data for the component, if any.
*
* The Installation Descriptor Extension data are located at the end of the
* <component> element of the installation descriptor.
*
* @return aa DOM document fragment containing the installation descriptor
* (jbi.xml) extension data, or null if none is present
* in the descriptor.
*/
public org.w3c.dom.DocumentFragment getInstallationDescriptorExtension();
/**
* Get the installation root directory full path name for this component.
* This path name must be formatted for the platform the JBI environment is
* running on.
*
* @return the installation root directory name, which must be non-null and
* non-empty.
*/
public java.lang.String getInstallRoot();
/**
* Returns true if this context was created in order to
* install a component into the JBI environment. Returns false
* if this context was created to uninstall a previously installed
* component.
*
* This method is provided to allow {@link Bootstrap} implementations to
* tailor their behaviour according to use case. For example, the
* {@link Bootstrap#init(InstallationContext)} method implementation may
* create different types of extension MBeans, depending on the use case
* specified by this method.
*
* @return true if this context was created in order to install
* a component into the JBI environment; otherwise the context was
* created to uninstall an existing component.
*/
public boolean isInstall();
/**
* Set the list of elements that comprise the class path for this component.
* Each element represents either a directory (containing class files) or a
* jar file. Elements are reached from the install root. These elements
* represent class path items that the component's execution-time component
* class loader uses, in search order. All file paths are relative to the
* install root of the component.
*
* This method allows the component's bootstrap to alter the execution-time
* class path specified by the component's installation descriptor. The
* component configuration determined during installation can affect the
* class path needed by the component at execution-time. All path elements
* must use the file separator character appropriate to the system (i.e.,
* File.separator.).
*
* @param classPathElements
* a list of String objects, each of which contains a class path
* elements; the list must be non-null and contain at least one
* class path element.
* @throws java.lang.IllegalArgumentException
* if the class path elements is null, empty, or if an
* individual element is ill-formed
*/
public void setClassPathElements(java.util.List classPathElements);
}