javax.jbi.messaging
Interface DeliveryChannel

public interface DeliveryChannel

Bi-directional communication channel used by engines and bindings (hereafter called JBI components) to interact with the Normalized Message Router. Each JBI component has one DeliveryChannel associated with it. Using the delivery channel, a component may:

• Receive message exchanges routed to the component (optionally, with a time-out).
• Send a message asynchronously (that is, without waiting for a response or status change acknowledging that the exchange was received).
• Send a message synchronously, blocking the thread of execution until the result is received. Optionally, this can be done with a time-out.

Author:

JSR208 Expert Group

Method Summary

MessageExchange	accept() TODO accept check multi thread Blocking call used to service a MessageExchange instance which has been initiated by another component.
MessageExchange	accept(long timeoutMS) TODO accept check multi thread Blocking call used to service a MessageExchange instance which has been initiated by another component, within the given timeout period.
void	close() TODO close pending messages, remove endpoint entries ? Closes the delivery channel, halting all message traffic.
MessageExchangeFactory	createExchangeFactory() Create a message exchange factory.
MessageExchangeFactory	createExchangeFactory(javax.xml.namespace.QName interfaceName) Create a message exchange factory for the given interface name.
MessageExchangeFactory	createExchangeFactory(ServiceEndpoint endpoint) Create a message exchange factory for the given endpoint.
MessageExchangeFactory	createExchangeFactoryForService(javax.xml.namespace.QName serviceName) Create a message exchange factory for the given service name.
void	send(MessageExchange exchange) TODO send resolve jbi logical endpoint Routes a MessageExchange instance through the Normalized Message Router to the appropriate servicing component.
boolean	sendSync(MessageExchange exchange) TODO sendSync check multithread Routes a MessageExchange instance through the Normalized Message Router to the appropriate servicing component, and blocks until the exchange is returned (that is, the other participant sends the message exchange back).
boolean	sendSync(MessageExchange exchange, long timeoutMS) TODO sendSync check multithread Routes a MessageExchange instance through the Normalized Message Router to the appropriate servicing component, and blocks until the exchange is returned (that is, the other participant sends the message exchange back), or the specified timeout interval elapses.

Method Detail

accept

MessageExchange accept()
                       throws MessagingException

TODO accept check multi thread Blocking call used to service a MessageExchange instance which has been initiated by another component. This method supports concurrent invocation for multi-threaded environments. This must be interruptable (Thread.interrupt()).

Returns:

message exchange instance; must be non-null

Throws:

MessagingException - failed to accept

MessagingException - when the blocked thread is interrupted

accept

MessageExchange accept(long timeoutMS)
                       throws MessagingException,
                              java.lang.IllegalArgumentException

TODO accept check multi thread Blocking call used to service a MessageExchange instance which has been initiated by another component, within the given timeout period. This method supports concurrent invocation for multi-threaded environments.

Parameters:

timeoutMS - timeout period, in milliseconds (0 means no timeout); must be greater than or equal to zero

Returns:

message exchange instance, or null if timed out

Throws:

java.lang.IllegalArgumentException - if timeoutMS < 0

MessagingException - failed to accept

MessagingException - when the blocked thread is interrupted

close

void close()
           throws MessagingException

TODO close pending messages, remove endpoint entries ? Closes the delivery channel, halting all message traffic.

Throws:

MessagingException - fatal error while closing channel

createExchangeFactory

MessageExchangeFactory createExchangeFactory()

Create a message exchange factory. This factory will create exchange instances with all appropriate properties set to null.

Returns:

a message exchange factory; must be non-null

createExchangeFactory

MessageExchangeFactory createExchangeFactory(javax.xml.namespace.QName interfaceName)

Create a message exchange factory for the given interface name.

Parameters:

interfaceName - name of the interface for which all exchanges created by the returned factory will be set for; may be null

Returns:

an exchange factory that will create exchanges for the the given interface; must be non-null

createExchangeFactory

MessageExchangeFactory createExchangeFactory(ServiceEndpoint endpoint)

Create a message exchange factory for the given endpoint.

Parameters:

endpoint - endpoint for which all exchanges created by the returned factory will be set for; may be null

Returns:

an exchange factory that will create exchanges for the given endpoint; must be non-null

createExchangeFactoryForService

MessageExchangeFactory createExchangeFactoryForService(javax.xml.namespace.QName serviceName)

Create a message exchange factory for the given service name.

Parameters:

serviceName - name of the service for which all exchanges created by the returned factory will be set for; may be null

Returns:

an exchange factory that will create exchanges for the the given service; must be non-null

send

void send(MessageExchange exchange)
          throws MessagingException

TODO send resolve jbi logical endpoint Routes a MessageExchange instance through the Normalized Message Router to the appropriate servicing component. This method supports concurrent invocation for multi-threaded environments.

This is used not only to send the initial message in an exchange, but also for the servicer to "return" the exchange with the appropriate response (response, fault, or ExchangeStatus). In more complex message exchange patterns, a single MessageExchange can be sent back-and-forth via send() several times, but always terminating with the MessageExchange instance being sent with a terminal ExchangeStatus.

Parameters:

exchange - message exchange to send; must be non-null

Throws:

MessagingException - unable to send exchange

sendSync

boolean sendSync(MessageExchange exchange)
                 throws MessagingException

TODO sendSync check multithread Routes a MessageExchange instance through the Normalized Message Router to the appropriate servicing component, and blocks until the exchange is returned (that is, the other participant sends the message exchange back). This method supports concurrent invocation for multi-threaded environments.

If the thread making this call is interrupted, the message exchange is treated in the same fashion as a timed-out sendSync call; see sendSync(MessageExchange, long).

Note that the "returned" message exchange (the instance returned by the other participant in the exchange) is the same instance referred to by the parameter exchange.

Parameters:

exchange - message exchange to send; must be non-null

Returns:

true if the exchange has been returned (always)

Throws:

MessagingException - unable to send exchange, or no response is expected from the send() operation (i.e., the MessageExchange is being used to convey an ExchangeStatus)

MessagingException - when the blocked thread is interrupted

sendSync

boolean sendSync(MessageExchange exchange,
                 long timeoutMS)
                 throws MessagingException

TODO sendSync check multithread Routes a MessageExchange instance through the Normalized Message Router to the appropriate servicing component, and blocks until the exchange is returned (that is, the other participant sends the message exchange back), or the specified timeout interval elapses. This method supports concurrent invocation for multi-threaded environments.

If the thread making this call is interrupted while this method is blocked, the message exchange is treated as if the time out occurred.

If this method returns false (indicating that timeout occurred), the message exchange must be marked by the implementation as being in the ExchangeStatus.ERROR state. Attempts by the service provider to send a MessageExchange in such an ERROR state must result in the send (or sendSync) method called ending abruptly with an appropriate MessagingException.

Note that the "returned" message exchange (the instance returned by the other participant in the exchange) is the same instance referred to by the parameter exchange.

Parameters:

exchange - message exchange to send; must be non-null

timeoutMS - timeout period, in milliseconds (0 means no timeout); must be greater than or equal to zero

Returns:

true if the exchange has been returned, or false if the method timed out while waiting

Throws:

java.lang.IllegalArgumentException - if timeoutMS < 0

MessagingException - unable to send exchange, or no response is expected from the send() operation (i.e., the MessageExchange is being used to convey an ExchangeStatus)

MessagingException - when the blocked thread is interrupted