oracle.sdp.messaging.driver
Interface DriverConnection

All Known Subinterfaces:

DriverManagedConnection

All Known Implementing Classes:

DriverManagedConnectionBase

public interface DriverConnection

The Messaging driver dispatcher (or Messaging engine) facing driver connection interface. A driver connection is used by the Messaging Driver Dispatcher to access third-party remote gateways. More gateways can be supported by Messaging by plugging in more drivers.

Since:

11.0.0

Field Summary

static int

MESSAGE_ID_MAX_LENGTH The maximum length in characters the returned message id can be.

Method Summary

CancelResultType	cancel(java.lang.String gatewayMessageId) Cancel a message sent.
void	close() Close this driver connection instance.
MessageListener	getMessageListener() This provides the ability to a non-JCA driver component to get the callback message listener for inbound messaging (and status reporting) from this driver connection.
Status	getStatus(java.lang.String gatewayMessageId) Get the sending status of a message.
WorkingStateType	getWorkingState() Check if this connection is still able to send (and/or receive) messages.
void	processHttpServletRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) This is a helper method defined for drivers that have HTTP based protocols, and use a servlet to process incoming HTTP requests.
void	registerMessageListener(MessageListener listener) This provides the ability to a client of this connection to register a callback message listener for inbound messages.
Status	replace(java.lang.String gatewayMessageId, Message message) Replace a message sent.
List<Status>	send(Message message) Send a message with this driver.
void	unregisterMessageListener() This removes a previously registered message listener from this connection.

Field Detail

MESSAGE_ID_MAX_LENGTH

static final int MESSAGE_ID_MAX_LENGTH

The maximum length in characters the returned message id can be.

See Also:

Constant Field Values

Method Detail

cancel

CancelResultType cancel(java.lang.String gatewayMessageId)
                        throws DriverException

Cancel a message sent. Given a gateway/driver message id, cancel the message from the external gateway, if supported by the underlying messaging protocol.

Parameters:

gatewayMessageId - the message id assigned by the gateway/driver.

Returns:

CancelResultType.SUCCEEDED if the operation succeeded, CancelResultType.FAILED if the operation failed, CancelResultType.RETRY if the driver requested the operation to be retried later.

Throws:

DriverException - if there was an error during this operation.

close

void close()

Close this driver connection instance. The client (Driver Dispatcher) calls this method when it no longer needs this driver connection instance.

getMessageListener

MessageListener getMessageListener()
                                   throws DriverException

This provides the ability to a non-JCA driver component to get the callback message listener for inbound messaging (and status reporting) from this driver connection. This is useful in cases where the Driver has a servlet or web services based component for inbound messages (and status reports), and it needs to deliver these to the Messaging engine via the Driver RA facility.

Returns:

the registered message listener

Throws:

DriverException - if there is no registered message listener.

getStatus

Status getStatus(java.lang.String gatewayMessageId)
                 throws DriverException

Get the sending status of a message. The status got by this call should not be reported to the messaging system via the driver listener MDB onStatus callback. Only those statuses received by the driver when this call is not invoking should be reported to the messaging system via the driver lisener MDB onStatus callback. If the message id is unknown to the driver, or the driver can't get any status for the message, a null SendingStatus instance should be returned. When a null status is returned, the messaging system won't try to ask for the sending status for this message any more. If the driver is slow in getting the status back, and wants more time to try to get the sending status, the driver can return a status of StatusType.DELIVERY_TO_SERVER_SUCCESS so that the messaging system can try to ask for status again later on.

Parameters:

gatewayMessageId - the message id assigned by the gateway/driver.

Returns:

the sending status.

Throws:

DriverException - if there was an error during this operation.

getWorkingState

WorkingStateType getWorkingState()

Check if this connection is still able to send (and/or receive) messages.

The driver instance should check the network connection to the gateway, the status of the gateway and so on. If the driver can't find out what's going on now, it means the driver isn't working.

The driver instance can re-initialize itself if necessary.

Returns:

the working state of this connection.

processHttpServletRequest

void processHttpServletRequest(javax.servlet.http.HttpServletRequest request,
                               javax.servlet.http.HttpServletResponse response)
                               throws DriverException

This is a helper method defined for drivers that have HTTP based protocols, and use a servlet to process incoming HTTP requests. The servlet can pass the processing work to the Driver RA's Connection which has all the other state required to complete the processing, such as generating an inbound message or a status report for delivery to the Messaging engine. By default, this method is implemented by the DriverManagedConnectionBase (which throws a "NotImplemented" DriverException) , but any driver can override this method and use it from it's servlet. See the SampleReceiveServlet code part of the sample driver distribution.

Parameters:

request - the HTTP servlet request object

response - the HTTP servlet response object

Throws:

DriverException - if there was an error during this operation.

registerMessageListener

void registerMessageListener(MessageListener listener)
                             throws DriverException

This provides the ability to a client of this connection to register a callback message listener for inbound messages. This is useful in cases where the Driver's ResourceAdapter implementation class starts a connection to the remote gateway. This allows the resource adapter class to register the DriverContext.getMessageListener() with this connection for inbound messaging. In other situations for inbound messaging, this step is optional, since the Driver's ResourceAdapter implementation class would schedule Workers to handle the inbound messaging and they would be able to directly use the MessageListener from the DriverContext.

Parameters:

listener - the message listener

Throws:

DriverException - if an error was encountered while registering the message listener.

replace

Status replace(java.lang.String gatewayMessageId,
               Message message)
               throws DriverException

Replace a message sent. Given a gateway/driver message id, replace the message with the new information provided. It is equal to removing the message sent, and send the new message. But if the message is already delivered, the replace operation should fail.

Parameters:

gatewayMessageId - the message id assigned by the gateway/driver.

message - the message to send.

Returns:

a sending report object.

Throws:

DriverException - if there was an error during this operation.

send

List<Status> send(Message message)
                  throws DriverException

Send a message with this driver.

Drivers implement this method to perform whatever is appropriate for their particular protocols to send out messages. The content to deliver as well as the recipients is stored in the message object.

Further, the driver is expected to return a sending status report for each recipient. Each report should associate its recipient with a unique gateway (or driver) id (use Status.setGatewayMessageId(String) to assign this unique id). These ids will be used by the Messaging engine to query the status of the delivery to the recipients when necessary. Typically the remote gateway will provide a unique id per recipient, and that should be set as the gateway id in the report. However, in certain situations, if the remote gateway does not provide message identifiers, you may use the unique message id in the message (use Message.getId()) as the base to generate the unique gateway ids for the recipients.

Parameters:

message - the message to send.

Returns:

a list of sending status reports, one per recipient.

Throws:

DriverException - if there was an error during this operation.

unregisterMessageListener

void unregisterMessageListener()
                               throws DriverException

This removes a previously registered message listener from this connection.

Throws:

DriverException - if an error was encountered while unregistering the message listener.