javax.resource.spi.endpoint

Interface MessageEndpointFactory

public interface MessageEndpointFactory

This serves as a factory for creating message endpoints.

Version:

1.0

Author:

Ram Jeyaraman

Method Summary

Methods

Modifier and Type	Method and Description
MessageEndpoint	createEndpoint(XAResource xaResource) This is used to create a message endpoint.
MessageEndpoint	createEndpoint(XAResource xaResource, long timeout) This is used to create a message endpoint.
String	getActivationName() Returns a unique name for this message endpoint.
boolean	isDeliveryTransacted(Method method) This is used to find out whether message deliveries to a target method on a message listener interface that is implemented by a message endpoint will be transacted or not.

Method Detail

createEndpoint

MessageEndpoint createEndpoint(XAResource xaResource)
                               throws UnavailableException

This is used to create a message endpoint. The message endpoint is expected to implement the correct message listener type.

Parameters:

xaResource - an optional XAResource instance used to get transaction notifications when the message delivery is transacted.

Returns:

a message endpoint instance.

Throws:

UnavailableException - indicates a transient failure in creating a message endpoint. Subsequent attempts to create a message endpoint might succeed.

createEndpoint

MessageEndpoint createEndpoint(XAResource xaResource,
                             long timeout)
                               throws UnavailableException

This is used to create a message endpoint. The message endpoint is expected to implement the correct message listener type.

Parameters:

xaResource - an optional XAResource instance used to get transaction notifications when the message delivery is transacted.

timeout - an optional value used to specify the time duration (in milliseconds) within which the message endpoint needs to be created by the MessageEndpointFactory. Otherwise, the MessageEndpointFactory rejects the creation of the MessageEndpoint with an UnavailableException. Note, this does not offer real-time guarantees.

Returns:

a message endpoint instance.

Throws:

UnavailableException - indicates a transient failure in creating a message endpoint. Subsequent attempts to create a message endpoint might succeed.

isDeliveryTransacted

boolean isDeliveryTransacted(Method method)
                             throws NoSuchMethodException

This is used to find out whether message deliveries to a target method on a message listener interface that is implemented by a message endpoint will be transacted or not. The message endpoint may indicate its transacted delivery preferences (at a per method level) through its deployment descriptor. The message delivery preferences must not change during the lifetime of a message endpoint.

Parameters:

method - description of a target method. This information about the intended target method allows an application server to find out whether the target method call will be transacted or not.

Returns:

true, if message endpoint requires transacted message delivery.

Throws:

NoSuchMethodException - indicates that the specified method does not exist on the target endpoint.

getActivationName

String getActivationName()

Returns a unique name for this message endpoint. If the application has been deployed into a clustered application server then this method must return the same name for the same endpoint in each application server instance. Otherwise, a different name must be returned for every endpoint in every application in every application server instance. The name must consist of Java letters or digits (as defined in the Java Language Specification) or the ASCII underscore (_ or _). Since a subscription name may be visible to the user or administrator it is recommended that this name is at least partly human-readable. The resource adapter may use this value as a valid JMS subscription name, either on its own or in combination with the value returned by the BootstrapContext.getInstanceName method. This value may be used on its own if the subscription name needs to be the same for the same endpoint in each application server instance within a cluster but otherwise unique. This value may be used in combination with the value returned by the BootstrapContext.getInstanceName method if the subscription name needs to be unique to this endpoint. Since a durable subscription can be used to store messages indefinitely it is recommended that this name remains unchanged even if the application server is restarted or reconfigured, or if the application is redeployed. The combination of this value and the value returned by the BootstrapContext.getInstanceName method should be no longer than 128 characters.

Returns:

a new String instance.

See Also:

BootstrapContext