oracle.panama.messaging.transport
Interface Driver

public interface Driver

The driver interface. Driver is used by Messenger to access devices. More devices can be supported by the transport system via plug in more drivers.

Author:

jxiang

Field Summary

static int	FAILED Valid initialization status.
static int	MESSAGE_ID_MAX_LENGTH The maximum length in characters the returned message id can be.
static int	RECEIVE
static int	SEND
static int	SEND_RECEIVE

Method Summary

void	destroy() Destroy the driver.
java.lang.String	getInfo() Get additional information of the driver.
Parameter[]	getParameters() Get the expected parameter list.
void	getStatus(java.lang.String mid) Get the sending status of a message.
void	getStatus(java.lang.String[] mids) Get the sending statuses of a list of messages.
java.lang.String	getVersion() Get the version of the driver.
int	init(java.util.Properties properties) Initialize the driver.
boolean	queryNotifying() Check if query is required to get the notification.
boolean	queryTracking() Check if query is required to track the sending status.
void	receive() Drivers implement this method to perform whatever is appropriate for their particular protocols to receive messages.
java.lang.String[]	send(java.lang.String[] dtypes, java.lang.String[] addresses, int[] modes, java.lang.String encoding, int tracking, int expiration, int reliability, int priority, java.lang.String fromAddr, java.lang.String replyToAddr, java.lang.String mid, Message message) Send a message to a list of addresses with this driver.
java.lang.String[]	send(java.lang.String dtype, java.lang.String[] addresses, int[] modes, java.lang.String encoding, int tracking, int expiration, int reliability, int priority, java.lang.String fromAddr, java.lang.String replyToAddr, java.lang.String mid, Message message) Send a message to a list of addresses with this driver.
java.lang.String	send(java.lang.String dtype, java.lang.String address, int mode, java.lang.String encoding, int tracking, int expiration, int reliability, int priority, java.lang.String fromAddr, java.lang.String replyToAddr, java.lang.String mid, Message message) Send a message to a single address with this driver.

Field Detail

FAILED

public static final int FAILED

Valid initialization status. Status can also be logical ORed "|"

See Also:

Constant Field Values

SEND

public static final int SEND

See Also:

Constant Field Values

RECEIVE

public static final int RECEIVE

See Also:

Constant Field Values

SEND_RECEIVE

public static final int SEND_RECEIVE

See Also:

Constant Field Values

MESSAGE_ID_MAX_LENGTH

public 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

init

public int init(java.util.Properties properties)

Initialize the driver. Properties passed in include those custom to each driver type and values provided to each instance, as well as an implicit set of common properties in the OracleAS Wireless environment. Please consult product documentaion for more detail. The init method should return the initialization status as defined above. The return indicates the capability of the driver instance. The meaning of the status is quite self explanatory. However, one has to make sure the capability returned here is consistent with those configured over the UI. If they differ, those returned here takes precedence.

Parameters:

properties - the driver's properties.

Returns:

the initialization status.

getParameters

public Parameter[] getParameters()

Get the expected parameter list.

Returns:

an array of Parameter.

destroy

public void destroy()

Destroy the driver.

getVersion

public java.lang.String getVersion()

Get the version of the driver.

Returns:

the version of the driver.

getInfo

public java.lang.String getInfo()

Get additional information of the driver.

Returns:

the information of the driver.

send

public java.lang.String send(java.lang.String dtype,
                             java.lang.String address,
                             int mode,
                             java.lang.String encoding,
                             int tracking,
                             int expiration,
                             int reliability,
                             int priority,
                             java.lang.String fromAddr,
                             java.lang.String replyToAddr,
                             java.lang.String mid,
Message message)
                      throws DriverException

Send a message to a single address with this driver. Drivers implement this method to perform whatever is appropriate for their particular protocols to send out messages. The content to delivery is stored in the Message object passed onto the send() method, while the address parameter specifies one or more recipients to deliver the message to. Further, the driver is expected to return a unique id for each recipient, or ids one for each of the recipients. These ids will be used by the transport to query status of the delivery when necessary. The unique message id passed to the driver can be used as the base to generate the messaged id(s) for the recipient(s). The driver must return a null message ID to make the transport retry. Exceptions thrown out of the send method are ignored, except for exceptions of type DriverException. If the send () method throws an exception of the type DriverException, the transport will not retry. If the code of the exception is marked fatal, the sending capability of this driver instance is revoked. If the exception is not marked fatal, the driver will still be used to send other messages. If a valid message id is returned, its length should not have more than MESSAGE_ID_MAX_LENGTH characters.

Parameters:

dtype - the delivery type of the destination.

address - the address to send to.

mode - the delivery mode.

encoding - the encoding of the device.

tracking - the tracking level.

expiration - the expiration time.

reliability - the reliability level.

priority - the priority level.

fromAddr - the from-address.

replyToAddr - the reply-to-address.

mid - the unique id of the message.

message - the message to send.

Returns:

a unique message id, null if failed.

Throws:

DriverException.

DriverException

send

public java.lang.String[] send(java.lang.String dtype,
                               java.lang.String[] addresses,
                               int[] modes,
                               java.lang.String encoding,
                               int tracking,
                               int expiration,
                               int reliability,
                               int priority,
                               java.lang.String fromAddr,
                               java.lang.String replyToAddr,
                               java.lang.String mid,
Message message)
                        throws DriverException

Send a message to a list of addresses with this driver.

Parameters:

dtype - the delivery type of all destinations.

addresses - the addresses to send to.

modes - the delivery modes.

encoding - the encoding of the device.

tracking - the tracking level.

expiration - the expiration time.

reliability - the reliability level.

priority - the priority level.

fromAddr - the from-address.

replyToAddr - the reply-to-address.

mid - the unique id of the message.

message - the message to send.

Returns:

a list of unique message ids, null if failed.

Throws:

DriverException.

DriverException

send

public java.lang.String[] send(java.lang.String[] dtypes,
                               java.lang.String[] addresses,
                               int[] modes,
                               java.lang.String encoding,
                               int tracking,
                               int expiration,
                               int reliability,
                               int priority,
                               java.lang.String fromAddr,
                               java.lang.String replyToAddr,
                               java.lang.String mid,
Message message)
                        throws DriverException

Send a message to a list of addresses with this driver.

Parameters:

dtypes - the delivery types of correspondent destinations.

addresses - the addresses to send to.

modes - the delivery modes.

encoding - the encoding of the device.

tracking - the tracking level.

expiration - the expiration time.

reliability - the reliability level.

priority - the priority level.

fromAddr - the from-address.

replyToAddr - the reply-to-address.

mid - the unique id of the message.

message - the message to send.

Returns:

a list of unique message ids, null if failed.

Throws:

DriverException.

DriverException

getStatus

public void getStatus(java.lang.String mid)

Get the sending status of a message. The status got by this call should be reported the transport system via the driver listener onStatus callback.

Parameters:

mid - the id of the message.

getStatus

public void getStatus(java.lang.String[] mids)

Get the sending statuses of a list of messages. The statuses got by this call should be reported the transport system via the driver listener onStatus callback.

Parameters:

mids - the ids of these messages.

queryNotifying

public boolean queryNotifying()

Check if query is required to get the notification. With some protocols, an active poll to the external service must be performed to check status of messages previously sent. These methods are called by the Transport to determine whether a getStatus() must be issued to retrieve status, or the driver would pass status back to Transport without such call(in this case, typically the driver calls onStatus() inside receive() ).

Returns:

true if required, false otherwise.

queryTracking

public boolean queryTracking()

Check if query is required to track the sending status.

Returns:

true if required, false otherwise.

receive

public void receive()
             throws DriverException

Drivers implement this method to perform whatever is appropriate for their particular protocols to receive messages. The transport system would drive the operation. Normally, the driver is expected to return from this method once a message is received. This way controlled is yielded back to the transport regularly so that the transport and decide the best step to take next. The receive() method is called continuously by the transport. Hence it is preferable the receive() method blocks if it does not receive any messages. However it should not block indefinitely otherwise it will be considered a runaway operation and the thread that calls the receive will be terminated. The time elapse for runaway threads can be configured by setting "Maximum Execution Time per Request" under runtime configuration (default is 120 second). When a message is received, it should call the onMessage method of the Message Listener to submit the message (or, the onStatus callback on Status Listener if the message was a status report). The method can throw an exception of type DriverException and mark it fatal to ask the transport to stop calling the receive () method. The reason for this design is to simplify the logic and thread control of the driver.

Throws:

DriverException.

DriverException