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 }