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: * @(#)InstallationContext.java
025: * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
026: *
027: * END_HEADER - DO NOT EDIT
028: */
029: package javax.jbi.component;
030:
031: import org.w3c.dom.DocumentFragment;
032:
033: /**
034: * This context contains information necessary for a JBI component to
035: * perform its installation/uninstallation processing. This is provided to
036: * the init() method of the component {@link Bootstrap} interface.
037: *
038: * @author JSR208 Expert Group
039: */
040: public interface InstallationContext {
041: /**
042: * Get the name of the class that implements the {@link Component}
043: * interface for this component. This must be the component
044: * class name given in the component's installation descriptor.
045: *
046: * @return the {@link Component} implementation class name, which must be
047: * non-null and non-empty.
048: */
049: String getComponentClassName();
050:
051: /**
052: * Get a list of elements that comprise the class path for this component.
053: * Each element represents either a directory (containing class files) or a
054: * library file. All elements are reachable from the install root. These
055: * elements represent class path items that the component's execution-time
056: * component class loader uses, in search order. All path elements must
057: * use the file separator character appropriate to the system (i.e.,
058: * <code>File.separator</code>).
059: *
060: * @return a list of String objects, each of which contains a class path
061: * elements. The list must contain at least one class path element.
062: */
063: java.util.List getClassPathElements();
064:
065: /**
066: * Get the unique name assigned to this component. This name must be
067: * assigned from the component's installation descriptor identification
068: * section.
069: *
070: * @return the unique component name, which must be non-null and non-empty.
071: */
072: String getComponentName();
073:
074: /**
075: * Get the JBI context for this component. The following methods are
076: * valid to use on the context:
077: * <ul>
078: * <li>{@link ComponentContext#getLogger()}</li>
079: * <li>{@link ComponentContext#getMBeanNames()}</li>
080: * <li>{@link ComponentContext#getMBeanServer()}</li>
081: * <li>{@link ComponentContext#getNamingContext()}</li>
082: * <li>{@link ComponentContext#getTransactionManager()}</li>
083: * </ul>
084: * All other methods on the returned context must throw a
085: * <code>IllegalStateException</code> exception if invoked.
086: *
087: * @return the JBI context for this component, which must be non-null.
088: */
089: ComponentContext getContext();
090:
091: /**
092: * Get the installation root directory full path name for this component.
093: * This path name must be formatted for the platform the JBI environment
094: * is running on.
095: *
096: * @return the installation root directory name, which must be non-null and
097: * non-empty.
098: */
099: String getInstallRoot();
100:
101: /**
102: * Return a DOM document fragment representing the installation descriptor
103: * (jbi.xml) extension data for the component, if any.
104: * <p>
105: * The Installation Descriptor Extension data are located at the end of the
106: * <component> element of the installation descriptor.
107: *
108: * @return a DOM document fragment containing the installation descriptor
109: * (jbi.xml) extension data, or <code>null</code> if none is present in the
110: * descriptor.
111: */
112: DocumentFragment getInstallationDescriptorExtension();
113:
114: /**
115: * Returns <code>true</code> if this context was created in order to install
116: * a component into the JBI environment. Returns <code>false</code> if this
117: * context was created to uninstall a previously installed component.
118: * <p>
119: * This method is provided to allow {@link Bootstrap} implementations to
120: * tailor their behaviour according to use case. For example, the
121: * {@link Bootstrap#init(InstallationContext)} method implementation may
122: * create different types of extension MBeans, depending on the use case
123: * specified by this method.
124: *
125: * @return <code>true</code> if this context was created in order to install
126: * a component into the JBI environment; otherwise the context
127: * was created to uninstall an existing component.
128: */
129: boolean isInstall();
130:
131: /**
132: * Set the list of elements that comprise the class path for this component.
133: * Each element represents either a directory (containing class files) or a
134: * library file. Elements are reached from the install root. These
135: * elements represent class path items that the component's execution-time
136: * component class loader uses, in search order. All file paths are
137: * relative to the install root of the component.
138: * <p>
139: * This method allows the component's bootstrap to alter the execution-time
140: * class path specified by the component's installation descriptor. The
141: * component configuration determined during installation can affect the
142: * class path needed by the component at execution-time. All path elements
143: * must use the file separator character appropriate to the system (i.e.,
144: * <code>File.separator</code>.
145: *
146: * @param classPathElements a list of String objects, each of which contains
147: * a class path elements; the list must be non-null and contain at
148: * least one class path element.
149: * @exception IllegalArgumentException if the class path elements is null,
150: * empty, or if an individual element is ill-formed.
151: */
152: void setClassPathElements(java.util.List classPathElements);
153: }
|