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    }