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