com.sonicsw.xq
Interface XQEndpointManager

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
   
 

See Also:

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

getEndpoint

XQEndpoint getEndpoint(java.lang.String name)
                       throws XQEndpointCreationException,
                              XQEndpointNotFoundException

Retrieves an endpoint handle(XQEndpoint) designated by the specified name.

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.

Parameters:

name - The name of the endpoint.

Returns:

The designated endpoint handle.

Throws:

XQEndpointCreationException - if the endpoint could not be created.

XQEndpointNotFoundException

See Also:

createTransientEndpoint(com.sonicsw.esb.mgmtapi.config.IEndpointConfig), isEndpointDefined(java.lang.String), isEndpointConfigured(java.lang.String), isEndpointTransient(java.lang.String)

isEndpointDefined

boolean isEndpointDefined(java.lang.String name)

Indicates whether the named endpoint handle exists. The endpoint may be transient or configured.

Parameters:

name - The name of the endpoint.

Returns:

true if endpoint exists; else false

See Also:

getEndpoint(java.lang.String), createTransientEndpoint(com.sonicsw.esb.mgmtapi.config.IEndpointConfig)

isEndpointTransient

boolean isEndpointTransient(java.lang.String name)

Indicates whether the named endpoint is transient.

Parameters:

name - The name of the endpoint.

Returns:

true if endpoint is transient; else false

See Also:

createTransientEndpoint(com.sonicsw.esb.mgmtapi.config.IEndpointConfig), isEndpointDefined(java.lang.String), isEndpointConfigured(java.lang.String)

isEndpointConfigured

boolean isEndpointConfigured(java.lang.String name)

Indicates whether the named endpoint is configured in the Directory Service.

Parameters:

name - endpoint name

Returns:

true if endpoint is configured; else false

See Also:

isEndpointDefined(java.lang.String), isEndpointTransient(java.lang.String)

removeEndpoint

void removeEndpoint(java.lang.String name)
                    throws XQEndpointNotFoundException

Removes the XQEndpoint handle object designated by the specified name from the system. If the endpoint is configured in the Directory Service, this method does NOT remove the configuration. Since configured endpoint handles are shared by all endpoints in an ESB Container it is recommended that this method is not called against configured endpoints.

Parameters:

name - The name of the endpoint.

Throws:

XQEndpointNotFoundException - if the endpoint does not exist.

cloneEndpointConfig

IEndpointConfig cloneEndpointConfig(java.lang.String configuredEndpointName,
                                    java.lang.String transientEndpointName)
                                    throws XQEndpointNotFoundException

Clone an configured endpoint configuration, and create a new transient endpoint configuration. The new configuration may be further altered, then used for creating a transient endpoint.

Parameters:

configuredEndpointName - The endpoint name to clone configuration from

transientEndpointName - The transient endpoint name.

Returns:

The cloned configuration

Throws:

XQEndpointNotFoundException - if the existing endpoint does not exist

See Also:

IEndpointConfig

cloneEntryEndpointConfig

IEndpointConfig cloneEntryEndpointConfig(java.lang.String newEndpointName)
                                         throws XQEndpointNotFoundException

Clone the container configured entry endpoint configuration for this service , and create a new transient endpoint configuration. The new configuration may be further altered, then used for creating a transient endpoint.

Parameters:

newEndpointName - The new endpoint name.

Returns:

The cloned configuration

Throws:

XQEndpointNotFoundException

See Also:

IEndpointConfig

createTransientEndpoint

XQEndpoint createTransientEndpoint(IEndpointConfig config)
                                   throws XQEndpointCreationException

Creates a transient endpoint from an endpoint configuration and register the endpoint with the service endpoint manager

Parameters:

config - the configuration

Returns:

The endpoint handle

Throws:

XQEndpointException - if the endpoint already exists, etc

XQEndpointCreationException

registerAsEntryEndpoint

void registerAsEntryEndpoint(XQEndpoint endpoint,
                             int numListeners)
                             throws XQException

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.

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.

Parameters:

endpoint -

numListeners - number of service threads that can be concurrently processing messages that arrive at this endpoint.

Throws:

XQException

See Also:

unregisterAsEntryEndpoint(com.sonicsw.xq.XQEndpoint)

unregisterAsEntryEndpoint

void unregisterAsEntryEndpoint(XQEndpoint endpoint)
                               throws XQException

Unregisters an endpoint as a means for dispatching to the current service. This method ONLY unregisters listeners that have been registered by the registerAsEntryEndpoint method. As a result you cannot unlisten the configured entry endpoint listeners that are created by the ESB Container at startup. If the endpoint listener is currently dispatching a message, and, the message is being delivered with an ESB ExactlyOnce Quality of Service, the message may be re-delivered. Re-delivered messages can be identified by examining the "JMSRedelivered" header value.

Parameters:

endpoint -

Throws:

XQException

See Also:

registerAsEntryEndpoint(com.sonicsw.xq.XQEndpoint, int)

getEntryEndpoint

java.lang.String getEntryEndpoint(XQMessage msg)

Helper method to determine the entry endpoint through which a message was received

Parameters:

msg - The request message.

Returns:

The name of the dispatching endpoint, null if unavailable

Throws:

XQEndpointException - In the event of some provider failure.