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