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 }