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    }