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 java.util.MissingResourceException; 020 import java.util.logging.Logger; 021 022 import javax.jbi.JBIException; 023 import javax.jbi.messaging.DeliveryChannel; 024 import javax.jbi.messaging.MessagingException; 025 import javax.jbi.servicedesc.ServiceEndpoint; 026 027 import javax.xml.namespace.QName; 028 029 import org.w3c.dom.Document; 030 import org.w3c.dom.DocumentFragment; 031 032 /** 033 * This interface provides access to data needed by a JBI component 034 * about the JBI environment in which it is installed, as well providing 035 * the means to allow the component to inform the JBI environment about 036 * services provided by this component. This interface provides methods 037 * for the following functions: 038 * <ul> 039 * <li>Get the <bold>DeliveryChannel</bold> for this component. This is 040 * required to allow the component to send and receive message 041 * exchanges.</li> 042 * <li><bold>Activate</bold> (and deactivate) service endpoints provided 043 * by this component.</li> 044 * <li><bold>Register</bold> (and deregister) external endpoints provided 045 * by this component.</li> 046 * <li><bold>Query</bold> available endpoints (internal and external).</li> 047 * <li><bold>Query</bold> various data about the component, as installed 048 * in the JBI environment (name, workspace root, install root, initial 049 * JNDI context, MBean Server, Transaction Manager).</li> 050 * <li><bold>Loggers</bold>. Obtain the component's logger and subloggers.</li> 051 * <li><bold>MBean name creator</bold>. Access a utility for creating 052 * custom MBean names.</li> 053 * <li><bold>EPR Resolver</bold>. Ask JBI to resolve an endpoint reference 054 * (EPR), converting it into a service endpoint.</li> 055 * 056 * Note: The term "NMR" (meaning Normalized Message Router) is used here to refer 057 * to the messaging system of the JBI implementation. This term is used as a 058 * synonym for the JBI implementation, and refers only to the logical message 059 * routing functions of a JBI implementation. It is not meant to require that 060 * JBI implementations literally have a subsystem named "NMR". 061 * 062 * @author JSR208 Expert Group 063 */ 064 public interface ComponentContext { 065 066 /** 067 * Activates the named endpoint with the NMR. Activation indicates to the NMR 068 * that this component is ready to process requests sent to the named endpoint. 069 * 070 * Note that the JBI implementation may call this component's 071 * {@link Component#getServiceDescription(ServiceEndpoint)} method before returning 072 * from this method call; the component's implementation must be ready to supply 073 * service description metadata before the result of this activation call (a 074 * ServiceEndpoint) is known. 075 * 076 * @param serviceName qualified name of the service the endpoint exposes; must 077 * be non-null. 078 * @param endpointName the name of the endpoint to be activated; must be non-null 079 * and non-empty. 080 * @return a reference to the activated endpoint; must be non-null. 081 * @throws JBIException if the endpoint cannot be activated. 082 */ 083 ServiceEndpoint activateEndpoint(QName serviceName, String endpointName) throws JBIException; 084 085 086 /** 087 * Deactivates the given endpoint with the NMR. Deactivation indicates to the NMR 088 * that this component will no longer process requests sent to the named endpoint. 089 * 090 * @param endpoint reference to the endpoint to be deactivated; must be non-null. 091 * @throws JBIException if the endpoint cannot be deactivated. 092 */ 093 void deactivateEndpoint(ServiceEndpoint endpoint) throws JBIException; 094 095 /** 096 * Registers the given external endpoint with the NMR. This indicates to the NMR that 097 * the given endpoint is used as a proxy for external service consumers to access an 098 * internal service of the same service name (but a different endpoint name). 099 * 100 * @param externalEndpoint the external endpoint to be registered, must be non-null. 101 * @throws JBIException if an external endpoint with the same name is already registered, 102 * by this or another component. 103 */ 104 void registerExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException; 105 106 /** 107 * Deregisters the given external endpoint with the NMR. This indicates to the NMR that 108 * the given external endpoint can no longer be used as a proxy for external service 109 * consumers to access an internal service of the same service name. 110 * 111 * @param externalEndpoint the external endpoint to be deregistered; must be non-null. 112 * @throws JBIException if the given external endpoint was not previously registered. 113 */ 114 void deregisterExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException; 115 116 /** 117 * Resolve the given endpoint reference into a service endpoint. This is called by the 118 * component when it has an EPR that it wants to resolve into a service endpoint. 119 * 120 * Note that the service endpoint returned refers to a dynamic endpoint; the endpoint 121 * will exist only as long as this component retains a strong reference to the object 122 * returned by this method. The endpoint may not be included in the list of "activated" 123 * endpoints. 124 * 125 * @param epr endpoint reference as an XML fragment; must be non-null. 126 * @return the service endpoint corresponding to the given endpoint reference; null if 127 * the reference cannot be resolved. 128 */ 129 ServiceEndpoint resolveEndpointReference(DocumentFragment epr); 130 131 /** 132 * Get the unique component name of this component, ass assigned by the identification 133 * section of this component's installation descriptor. 134 * 135 * @return the component name; must be non-null and non-empty. 136 */ 137 String getComponentName(); 138 139 /** 140 * Get a channel for this component to use to communicate with the Normalized Message 141 * Router. This channel must be used by the component to send and receive message 142 * exchanges. 143 * 144 * @return the delivery channel for this component; must be non-null. 145 * @throws MessagingException if a channel has already been opened, but not yet closed. 146 */ 147 DeliveryChannel getDeliveryChannel() throws MessagingException; 148 149 /** 150 * Get the service endpoint for the named activated endpoint, if any. 151 * 152 * @param service qualified-name of the endpoint's service; must be non-null. 153 * @param name name of the endpoint; must be non-null. 154 * @return the named endpoint, or null if the named endpoint is not activated. 155 */ 156 ServiceEndpoint getEndpoint(QName service, String name); 157 158 /** 159 * Retrieve the service description metadata for the specified endpoint. 160 * 161 * Note that the result can use either the WSDL 1.1 or WSDL 2.0 description language. 162 * 163 * @param endpoint endpoint reference; must be non-null. 164 * @return metadata describing endpoint, or null if metadata is unavailable. 165 * @throws JBIException invalid endpoint reference. 166 */ 167 Document getEndpointDescriptor(ServiceEndpoint endpoint) throws JBIException; 168 169 /** 170 * Queries the NMR for active endpoints that implement the given interface. This 171 * will return the endpoints for all services and endpoints that implement the 172 * named interface (portType in WSDL 1.1). This method does NOT include external 173 * endpoints (those registered using {@link #registerExternalEndpoint(ServiceEndpoint)}). 174 * 175 * @param interfaceName qualified name of interface/portType that is implemented 176 * by the endpoint; if null then all activated endpoints in 177 * the JBI environment must be returned. 178 * @return an array of available endpoints for the specified interface name; must 179 * be non-null; may be empty. 180 */ 181 ServiceEndpoint[] getEndpoints(QName interfaceName); 182 183 /** 184 * Queries the NMR for active endpoints belonging to the given service. This 185 * method does NOT include external endpoints (those registered using 186 * {@link #registerExternalEndpoint(ServiceEndpoint)}). 187 * 188 * @param serviceName qualified name of the service that the endpoints are part 189 * of; must be non-null. 190 * @return an array of available endpoints for the specified service name; must 191 * be non-null; may be empty. 192 */ 193 ServiceEndpoint[] getEndpointsForService(QName serviceName); 194 195 /** 196 * Queries the NMR for external endpoints that implement the given interface name. 197 * This methods returns only registered external endpoints (see 198 * {@link #registerExternalEndpoint(ServiceEndpoint)}). 199 * 200 * @param interfaceName qualified name of interface implemented by the endpoints; 201 * must be non-null. 202 * @return an array of available external endpoints for the specified interface name; 203 * must be non-null; may be empty. 204 */ 205 ServiceEndpoint[] getExternalEndpoints(QName interfaceName); 206 207 /** 208 * Queries the NMR for external endpoints that are part of the given service. 209 * 210 * @param serviceName qualified name of service that contains the endpoints; 211 * must be non-null. 212 * @return an array of available external endpoints for the specified service name; 213 * must be non-null; may be empty. 214 */ 215 ServiceEndpoint[] getExternalEndpointsForService(QName serviceName); 216 217 /** 218 * Get the installation root directory path for this component. 219 * 220 * This method MUST return the file path formatted for the underlying platform. 221 * 222 * @return the installation root directory path, in platform-specific form; 223 * must be non-null and non-empty. 224 */ 225 String getInstallRoot(); 226 227 /** 228 * Get a logger instance from JBI. Loggers supplied by JBI are guaranteed to have 229 * unique names such that they avoid name collisions with loggers from other 230 * components created using this method. The suffix parameter allows for the 231 * creation of subloggers as needed. The JBI specification says nothing about 232 * the exact names to be used, only that they must be unique across components 233 * and the JBI implementation itself. 234 * 235 * @param suffix for creating subloggers; use an empty string for the base component 236 * logger; must be non-null. 237 * @param resourceBundleName name of ResourceBundle to be used for localizing messages 238 * for the logger. May be null if none of the messages require 239 * localization. The resource, if non-null, must be loadable 240 * using the component's class loader as the initiating loader. 241 * @return a standard logger, named uniquely for this component (plus the given suffix, 242 * if applicable); must be non-null. 243 * @throws java.util.MissingResourceException if the ResourceBundleName is non-null and no 244 * corresponding resource can be found. 245 * @throws JBIException if the resourceBundleName has changed from a previous invocation 246 * by this component of this method with the same suffix. 247 */ 248 Logger getLogger(String suffix, String resourceBundleName) throws MissingResourceException, JBIException; 249 250 /** 251 * Get a reference to the MBeanNames creator for use in creating custom MBean names. 252 * 253 * @return reference to the MBeanNames creator; must be non-null. 254 */ 255 javax.jbi.management.MBeanNames getMBeanNames(); 256 257 /** 258 * Get the JMX MBean server used to register all MBeans in the JBI environment. 259 * 260 * @return a reference to the MBean server; must be non-null. 261 */ 262 javax.management.MBeanServer getMBeanServer(); 263 264 /** 265 * Get the JNDI naming context for this component. This context is a standard JNDI 266 * InitialContext but its content will vary based on the environment in which the JBI 267 * implementation is running. 268 * 269 * @return the JNDI naming context; must be non-null. 270 */ 271 javax.naming.InitialContext getNamingContext(); 272 273 /** 274 * Get the TransactionManager for this implementation. The instance returned is an 275 * implementation of the standard JTA interface. If none is available, this method 276 * returns null. 277 * 278 * The object returned by this method is untyped, to allow this interface to be compiled 279 * in environments that do not support JTA. If not null, the object returned must be of 280 * type javax.transaction.TransactionManager. 281 * 282 * This downcast is necessary because JBI is used in environments that do not support 283 * JTA (i.e., J2SE). Explicit use of JTA types would cause compilation failures in 284 * such environments. 285 * 286 * @return A TransactionManager instance, or null if none is available in the 287 * execution environment. 288 */ 289 Object getTransactionManager(); 290 291 /** 292 * Get the root directory path for this component's private workspace. 293 * 294 * This method MUST return the file path formatted for the underlying platform. 295 * 296 * The returned value must indicate a valid file path that the component may use 297 * to write files to, and read files from. 298 * 299 * @return the private workspace root path, in platform-specific form; 300 * must be non-null and non-empty. 301 */ 302 String getWorkspaceRoot(); 303 304 }