| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package javax.jbi.component; |
| |
| import java.util.MissingResourceException; |
| import java.util.logging.Logger; |
| |
| import javax.jbi.JBIException; |
| import javax.jbi.messaging.DeliveryChannel; |
| import javax.jbi.messaging.MessagingException; |
| import javax.jbi.servicedesc.ServiceEndpoint; |
| |
| import javax.xml.namespace.QName; |
| |
| import org.w3c.dom.Document; |
| import org.w3c.dom.DocumentFragment; |
| |
| /** |
| * This interface provides access to data needed by a JBI component |
| * about the JBI environment in which it is installed, as well providing |
| * the means to allow the component to inform the JBI environment about |
| * services provided by this component. This interface provides methods |
| * for the following functions: |
| * <ul> |
| * <li>Get the <bold>DeliveryChannel</bold> for this component. This is |
| * required to allow the component to send and receive message |
| * exchanges.</li> |
| * <li><bold>Activate</bold> (and deactivate) service endpoints provided |
| * by this component.</li> |
| * <li><bold>Register</bold> (and deregister) external endpoints provided |
| * by this component.</li> |
| * <li><bold>Query</bold> available endpoints (internal and external).</li> |
| * <li><bold>Query</bold> various data about the component, as installed |
| * in the JBI environment (name, workspace root, install root, initial |
| * JNDI context, MBean Server, Transaction Manager).</li> |
| * <li><bold>Loggers</bold>. Obtain the component's logger and subloggers.</li> |
| * <li><bold>MBean name creator</bold>. Access a utility for creating |
| * custom MBean names.</li> |
| * <li><bold>EPR Resolver</bold>. Ask JBI to resolve an endpoint reference |
| * (EPR), converting it into a service endpoint.</li> |
| * |
| * Note: The term "NMR" (meaning Normalized Message Router) is used here to refer |
| * to the messaging system of the JBI implementation. This term is used as a |
| * synonym for the JBI implementation, and refers only to the logical message |
| * routing functions of a JBI implementation. It is not meant to require that |
| * JBI implementations literally have a subsystem named "NMR". |
| * |
| * @author JSR208 Expert Group |
| */ |
| public interface ComponentContext { |
| |
| /** |
| * Activates the named endpoint with the NMR. Activation indicates to the NMR |
| * that this component is ready to process requests sent to the named endpoint. |
| * |
| * Note that the JBI implementation may call this component's |
| * {@link Component#getServiceDescription(ServiceEndpoint)} method before returning |
| * from this method call; the component's implementation must be ready to supply |
| * service description metadata before the result of this activation call (a |
| * ServiceEndpoint) is known. |
| * |
| * @param serviceName qualified name of the service the endpoint exposes; must |
| * be non-null. |
| * @param endpointName the name of the endpoint to be activated; must be non-null |
| * and non-empty. |
| * @return a reference to the activated endpoint; must be non-null. |
| * @throws JBIException if the endpoint cannot be activated. |
| */ |
| ServiceEndpoint activateEndpoint(QName serviceName, String endpointName) throws JBIException; |
| |
| |
| /** |
| * Deactivates the given endpoint with the NMR. Deactivation indicates to the NMR |
| * that this component will no longer process requests sent to the named endpoint. |
| * |
| * @param endpoint reference to the endpoint to be deactivated; must be non-null. |
| * @throws JBIException if the endpoint cannot be deactivated. |
| */ |
| void deactivateEndpoint(ServiceEndpoint endpoint) throws JBIException; |
| |
| /** |
| * Registers the given external endpoint with the NMR. This indicates to the NMR that |
| * the given endpoint is used as a proxy for external service consumers to access an |
| * internal service of the same service name (but a different endpoint name). |
| * |
| * @param externalEndpoint the external endpoint to be registered, must be non-null. |
| * @throws JBIException if an external endpoint with the same name is already registered, |
| * by this or another component. |
| */ |
| void registerExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException; |
| |
| /** |
| * Deregisters the given external endpoint with the NMR. This indicates to the NMR that |
| * the given external endpoint can no longer be used as a proxy for external service |
| * consumers to access an internal service of the same service name. |
| * |
| * @param externalEndpoint the external endpoint to be deregistered; must be non-null. |
| * @throws JBIException if the given external endpoint was not previously registered. |
| */ |
| void deregisterExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException; |
| |
| /** |
| * Resolve the given endpoint reference into a service endpoint. This is called by the |
| * component when it has an EPR that it wants to resolve into a service endpoint. |
| * |
| * Note that the service endpoint returned refers to a dynamic endpoint; the endpoint |
| * will exist only as long as this component retains a strong reference to the object |
| * returned by this method. The endpoint may not be included in the list of "activated" |
| * endpoints. |
| * |
| * @param epr endpoint reference as an XML fragment; must be non-null. |
| * @return the service endpoint corresponding to the given endpoint reference; null if |
| * the reference cannot be resolved. |
| */ |
| ServiceEndpoint resolveEndpointReference(DocumentFragment epr); |
| |
| /** |
| * Get the unique component name of this component, ass assigned by the identification |
| * section of this component's installation descriptor. |
| * |
| * @return the component name; must be non-null and non-empty. |
| */ |
| String getComponentName(); |
| |
| /** |
| * Get a channel for this component to use to communicate with the Normalized Message |
| * Router. This channel must be used by the component to send and receive message |
| * exchanges. |
| * |
| * @return the delivery channel for this component; must be non-null. |
| * @throws MessagingException if a channel has already been opened, but not yet closed. |
| */ |
| DeliveryChannel getDeliveryChannel() throws MessagingException; |
| |
| /** |
| * Get the service endpoint for the named activated endpoint, if any. |
| * |
| * @param service qualified-name of the endpoint's service; must be non-null. |
| * @param name name of the endpoint; must be non-null. |
| * @return the named endpoint, or null if the named endpoint is not activated. |
| */ |
| ServiceEndpoint getEndpoint(QName service, String name); |
| |
| /** |
| * Retrieve the service description metadata for the specified endpoint. |
| * |
| * Note that the result can use either the WSDL 1.1 or WSDL 2.0 description language. |
| * |
| * @param endpoint endpoint reference; must be non-null. |
| * @return metadata describing endpoint, or null if metadata is unavailable. |
| * @throws JBIException invalid endpoint reference. |
| */ |
| Document getEndpointDescriptor(ServiceEndpoint endpoint) throws JBIException; |
| |
| /** |
| * Queries the NMR for active endpoints that implement the given interface. This |
| * will return the endpoints for all services and endpoints that implement the |
| * named interface (portType in WSDL 1.1). This method does NOT include external |
| * endpoints (those registered using {@link #registerExternalEndpoint(ServiceEndpoint)}). |
| * |
| * @param interfaceName qualified name of interface/portType that is implemented |
| * by the endpoint; if null then all activated endpoints in |
| * the JBI environment must be returned. |
| * @return an array of available endpoints for the specified interface name; must |
| * be non-null; may be empty. |
| */ |
| ServiceEndpoint[] getEndpoints(QName interfaceName); |
| |
| /** |
| * Queries the NMR for active endpoints belonging to the given service. This |
| * method does NOT include external endpoints (those registered using |
| * {@link #registerExternalEndpoint(ServiceEndpoint)}). |
| * |
| * @param serviceName qualified name of the service that the endpoints are part |
| * of; must be non-null. |
| * @return an array of available endpoints for the specified service name; must |
| * be non-null; may be empty. |
| */ |
| ServiceEndpoint[] getEndpointsForService(QName serviceName); |
| |
| /** |
| * Queries the NMR for external endpoints that implement the given interface name. |
| * This methods returns only registered external endpoints (see |
| * {@link #registerExternalEndpoint(ServiceEndpoint)}). |
| * |
| * @param interfaceName qualified name of interface implemented by the endpoints; |
| * must be non-null. |
| * @return an array of available external endpoints for the specified interface name; |
| * must be non-null; may be empty. |
| */ |
| ServiceEndpoint[] getExternalEndpoints(QName interfaceName); |
| |
| /** |
| * Queries the NMR for external endpoints that are part of the given service. |
| * |
| * @param serviceName qualified name of service that contains the endpoints; |
| * must be non-null. |
| * @return an array of available external endpoints for the specified service name; |
| * must be non-null; may be empty. |
| */ |
| ServiceEndpoint[] getExternalEndpointsForService(QName serviceName); |
| |
| /** |
| * Get the installation root directory path for this component. |
| * |
| * This method MUST return the file path formatted for the underlying platform. |
| * |
| * @return the installation root directory path, in platform-specific form; |
| * must be non-null and non-empty. |
| */ |
| String getInstallRoot(); |
| |
| /** |
| * Get a logger instance from JBI. Loggers supplied by JBI are guaranteed to have |
| * unique names such that they avoid name collisions with loggers from other |
| * components created using this method. The suffix parameter allows for the |
| * creation of subloggers as needed. The JBI specification says nothing about |
| * the exact names to be used, only that they must be unique across components |
| * and the JBI implementation itself. |
| * |
| * @param suffix for creating subloggers; use an empty string for the base component |
| * logger; must be non-null. |
| * @param resourceBundleName name of ResourceBundle to be used for localizing messages |
| * for the logger. May be null if none of the messages require |
| * localization. The resource, if non-null, must be loadable |
| * using the component's class loader as the initiating loader. |
| * @return a standard logger, named uniquely for this component (plus the given suffix, |
| * if applicable); must be non-null. |
| * @throws java.util.MissingResourceException if the ResourceBundleName is non-null and no |
| * corresponding resource can be found. |
| * @throws JBIException if the resourceBundleName has changed from a previous invocation |
| * by this component of this method with the same suffix. |
| */ |
| Logger getLogger(String suffix, String resourceBundleName) throws MissingResourceException, JBIException; |
| |
| /** |
| * Get a reference to the MBeanNames creator for use in creating custom MBean names. |
| * |
| * @return reference to the MBeanNames creator; must be non-null. |
| */ |
| javax.jbi.management.MBeanNames getMBeanNames(); |
| |
| /** |
| * Get the JMX MBean server used to register all MBeans in the JBI environment. |
| * |
| * @return a reference to the MBean server; must be non-null. |
| */ |
| javax.management.MBeanServer getMBeanServer(); |
| |
| /** |
| * Get the JNDI naming context for this component. This context is a standard JNDI |
| * InitialContext but its content will vary based on the environment in which the JBI |
| * implementation is running. |
| * |
| * @return the JNDI naming context; must be non-null. |
| */ |
| javax.naming.InitialContext getNamingContext(); |
| |
| /** |
| * Get the TransactionManager for this implementation. The instance returned is an |
| * implementation of the standard JTA interface. If none is available, this method |
| * returns null. |
| * |
| * The object returned by this method is untyped, to allow this interface to be compiled |
| * in environments that do not support JTA. If not null, the object returned must be of |
| * type javax.transaction.TransactionManager. |
| * |
| * This downcast is necessary because JBI is used in environments that do not support |
| * JTA (i.e., J2SE). Explicit use of JTA types would cause compilation failures in |
| * such environments. |
| * |
| * @return A TransactionManager instance, or null if none is available in the |
| * execution environment. |
| */ |
| Object getTransactionManager(); |
| |
| /** |
| * Get the root directory path for this component's private workspace. |
| * |
| * This method MUST return the file path formatted for the underlying platform. |
| * |
| * The returned value must indicate a valid file path that the component may use |
| * to write files to, and read files from. |
| * |
| * @return the private workspace root path, in platform-specific form; |
| * must be non-null and non-empty. |
| */ |
| String getWorkspaceRoot(); |
| |
| } |