|
Sonic ESB API | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface XQEndpointManager
The XQEndpointManager creates and manages access to XQEndpoints used by an ESB Service. Applications access XQEndpoints by name through their XQEndpointManager. Endpoints may be configured in the Directory Service, or, created on the fly as transient endpoints by cloning and tailoring existing endpoint configurations. XQEndpointManager provides methods for cloning and creation of transient endpoints.
XQEndpointManager provides additional capabilities to an ESB service to programmatically register additional entry endpoints for dispatching purposes. Entry endpoints can be configured in the Directory Service, or transiently created.
Transient endpoints do not persist in the DirectoryService, nor are they visible in the XQConfigManager. Transient endpoints are scoped to the service instance that created them(XQEndpointManager scope) for sending and receiving. They are named for ease of use, names must be unique across the service instance, but cannot conflict with configured endpoint names.
Transient endpoints are available for the container lifetime, or removed by the removeEndpoint method.
Transient endpoints may not be directly referenced in URLs that are supported by the Sonic environment. For example, URLs like sonic://local/MyService:MyEndpoint can only reference endpoints that are configured. Therefore, transient endpoints may not be specified as the target of a Web Service invocations(SOAP or native ESB bindings).
On the otherhand, transient endpoints can be indirectly referenced through JNDI URLs that point to the underlying JMS destination.
Support for transient endpoints that are not JMS endpoints may be limited. JMS endpoints may reference temporary JMS destinations, however temporary JMS destination creation is not implemented by this API.
An XQEndpointManager is provided to each service through the XQInitContext method getEndpointManager().
Unless otherwise indicated all methods can be called in the service init() or
service() methods. For example, the methods to register and unregister
entry endpoints can be called whilst the service is running (from a service()
method). The method unregisterAsEntryEndpoint only removes registrations
created by registerAsEntryEndpoint. You cannot unregistered the configured
entry endpoint of a service.
The following code snippet illustrates API useage: ServiceA creates a transient endpoint that references a JMS destination QUEUE5. ServiceA registers the transient endpoint as an entry endpoint. String tempName = "DynamicSource"; XQEndpointManager mgr = myXQInitContext.getEndpointManager(); IEndpointConfig config = mgr.cloneEntryEndpointConfig("DynamicSource") ; IJMSEndpointConfig jmsadaptor = (IJMSEndpointConfig)config.getAdaptor(IJMSEndpointConfig.class); jmsadaptor.setDestinationName("QUEUE5"); XQEndpoint ep = mgr.createTransientEndpoint(config); mgr.registerAsEntryEndpoint(ep,4); ServiceB creates a transient endpoint, DynamicDestination, that references a JMS destination QUEUE5. This is the same destination that ServiceA is listening on. The endpoint is set up for a high send priority. ServiceB establishes an XQAddress for the transient endpoint. ServiceB processes a message and adds transient endpoint XQAddress to the envelope address list. The transient endpoint is included in the regular OUTBOX destinations when the ServiceB service() call returns. When dispatching to OUTBOX destinations note that the major ESB class of service aspects(JMS message persistence and transactions) are dictated by the environment that dispatches ServiceB(for example, a process QOS may be applied), and not the transient endpoint configuration for "DynamicDestination". String tempName = "DynamicDestination"; XQEndpointManager mgr = myXQInitContext.getEndpointManager(); IEndpointConfig config = mgr.cloneEndpointConfig("ServiceAEntry", "DynamicDestination") ; IJMSEndpointConfig jmsadaptor = (IJMSEndpointConfig)config.getAdaptor(IJMSEndpointConfig.class); jmsadaptor.setDestinationName("QUEUE5"); jmsadaptor.setPriority(8); XQEndpoint ep = mgr.createTransientEndpoint(config); XQAddress outboxAddress = myXQAddressFactory.createEndpointAddress("DynamicDestination"); currentEnvelope.addAddress(outboxAddress); ... and return from service method ServiceC creates a transient endpoint that references a JMS destination QUEUE5. This is the same destination that ServiceA is listening on. ServiceC also creates a transient endpoint that references a JMS destination QUEUE7. ServiceC registers itself to listen for replies against this endpoint. ServiceC creates an XQAddress for each transient endpoint, forms a message and adds the XQAddress to the envelope for sending and sets a ReplyTo with the transient endpoint against which ServiceC is registered. ServiceC directly dispatches the message and gets dispatched with the reply. When dispatching directly, note that the major ESB class of service aspects(JMS message persistence and transactions) are dictated by the dispatch call parameters. String tempName = "DynamicDestination"; XQEndpointManager mgr = myXQInitContext.getEndpointManager(); IEndpointConfig config = mgr.cloneEndpointConfig("ServiceAEntry", "DynamicDestination") ; IJMSEndpointConfig jmsadaptor = (IJMSEndpointConfig)config.getAdaptor(IJMSEndpointConfig.class); jmsadaptor.setDestinationName("QUEUE5"); jmsadaptor.setPriority(8); XQEndpoint ep = mgr.createTransientEndpoint(config); IEndpointConfig replyToConfig = mgr.cloneEntryEndpointConfig("DynamicReplyTo") ; IJMSEndpointConfig replyToJMSAdaptor = (IJMSEndpointConfig)replyToconfig.getAdaptor(IJMSEndpointConfig.class); replyToJMSAdaptor.setDestinationName("QUEUE7"); XQEndpoint replyToEP = mgr.createTransientEndpoint(replyToConfig); XQAddress replyToAddress = m_addressFactory.createEndpointAddress("DynamicReplyTo"); XQAddress address = myXQAddressFactory.createEndpointAddress("DynamicDestination"); newEnvelope.addAddress(address); newEnvelope.getMessage().setReplyTo(replyToAddress); myServiceDispatcher.dispatch(envelope, qos); ... and return from service method
XQEndpoint
Method Summary | |
---|---|
IEndpointConfig |
cloneEndpointConfig(java.lang.String configuredEndpointName,
java.lang.String transientEndpointName)
Clone an configured endpoint configuration, and create a new transient endpoint configuration. |
IEndpointConfig |
cloneEntryEndpointConfig(java.lang.String newEndpointName)
Clone the container configured entry endpoint configuration for this service , and create a new transient endpoint configuration. |
XQEndpoint |
createTransientEndpoint(IEndpointConfig config)
Creates a transient endpoint from an endpoint configuration and register the endpoint with the service endpoint manager |
XQEndpoint |
getEndpoint(java.lang.String name)
Retrieves an endpoint handle(XQEndpoint) designated by the specified name. |
java.lang.String |
getEntryEndpoint(XQMessage msg)
Helper method to determine the entry endpoint through which a message was received |
boolean |
isEndpointConfigured(java.lang.String name)
Indicates whether the named endpoint is configured in the Directory Service. |
boolean |
isEndpointDefined(java.lang.String name)
Indicates whether the named endpoint handle exists. |
boolean |
isEndpointTransient(java.lang.String name)
Indicates whether the named endpoint is transient. |
void |
registerAsEntryEndpoint(XQEndpoint endpoint,
int numListeners)
Register an endpoint as a means for dispatching to the current service For JMS, establishes JMS listener(s) against the endpoint through which messages can dispatch the current service. |
void |
removeEndpoint(java.lang.String name)
Removes the XQEndpoint handle object designated by the specified name from the system. |
void |
unregisterAsEntryEndpoint(XQEndpoint endpoint)
Unregisters an endpoint as a means for dispatching to the current service. |
Method Detail |
---|
XQEndpoint getEndpoint(java.lang.String name) throws XQEndpointCreationException, XQEndpointNotFoundException
Endpoints that are transient to the service (transient endpoints are not configured in the
DirectoryService) must first be created by the
createTransientEndpoint(IEndpointConfig)
method.
Transient endpoints are named; the name is scoped to the service instance.
Scope effects name visibility and uniqueness requirements.
Transient endpoint names cannot collide with configured endpoint names but
can collide with transient endpoint names in different service instances.
Endpoints that are configured in the Directory Service are uniquely named(globally scoped). For configured endpoints, each ESB container contains a single XQEndpoint handle object. For configured endpoints, this method creates an XQEndpoint handle if it not yet present in the ESB container
If an endpoint has neither been created as a transient endpoint nor is configured in the Directory Service this method throws a XQEndpointCreationException.
name
- The name of the endpoint.
XQEndpointCreationException
- if the endpoint could not be created.
XQEndpointNotFoundException
createTransientEndpoint(com.sonicsw.esb.mgmtapi.config.IEndpointConfig)
,
isEndpointDefined(java.lang.String)
,
isEndpointConfigured(java.lang.String)
,
isEndpointTransient(java.lang.String)
boolean isEndpointDefined(java.lang.String name)
name
- The name of the endpoint.
true
if endpoint exists; else false
getEndpoint(java.lang.String)
,
createTransientEndpoint(com.sonicsw.esb.mgmtapi.config.IEndpointConfig)
boolean isEndpointTransient(java.lang.String name)
name
- The name of the endpoint.
true
if endpoint is transient; else false
createTransientEndpoint(com.sonicsw.esb.mgmtapi.config.IEndpointConfig)
,
isEndpointDefined(java.lang.String)
,
isEndpointConfigured(java.lang.String)
boolean isEndpointConfigured(java.lang.String name)
name
- endpoint name
true
if endpoint is configured; else false
isEndpointDefined(java.lang.String)
,
isEndpointTransient(java.lang.String)
void removeEndpoint(java.lang.String name) throws XQEndpointNotFoundException
name
- The name of the endpoint.
XQEndpointNotFoundException
- if the endpoint does not exist.IEndpointConfig cloneEndpointConfig(java.lang.String configuredEndpointName, java.lang.String transientEndpointName) throws XQEndpointNotFoundException
configuredEndpointName
- The endpoint name to clone configuration fromtransientEndpointName
- The transient endpoint name.
XQEndpointNotFoundException
- if the existing endpoint does not existIEndpointConfig
IEndpointConfig cloneEntryEndpointConfig(java.lang.String newEndpointName) throws XQEndpointNotFoundException
newEndpointName
- The new endpoint name.
XQEndpointNotFoundException
IEndpointConfig
XQEndpoint createTransientEndpoint(IEndpointConfig config) throws XQEndpointCreationException
config
- the configuration
XQEndpointException
- if the endpoint already exists, etc
XQEndpointCreationException
void registerAsEntryEndpoint(XQEndpoint endpoint, int numListeners) throws XQException
Using this method you can only register transient endpoints.
The number of concurrent accesses to a service is restricted by the configured service listener count. This applies regardless of whether the service is dispatched internally, through its configured endpoint, or through an endpoint whose listeners are set up by this method. To increase concurrent service access, increase the service listener count.
endpoint
- numListeners
- number of service threads that can be concurrently processing
messages that arrive at this endpoint.
XQException
unregisterAsEntryEndpoint(com.sonicsw.xq.XQEndpoint)
void unregisterAsEntryEndpoint(XQEndpoint endpoint) throws XQException
endpoint
-
XQException
registerAsEntryEndpoint(com.sonicsw.xq.XQEndpoint, int)
java.lang.String getEntryEndpoint(XQMessage msg)
msg
- The request message.
XQEndpointException
- In the event of some provider failure.
|
Sonic ESB API | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |