Oracle Application Server Wireless Java API Reference
B10400-01

oracle.panama.messaging.transport
Interface Messenger


public interface Messenger
 This is the main interface for messaging APIs.
 
 The messenger is the main interface used by client
 applications to send/receive messages.  A messenger
 instance is specific to an application/service. 

 The messenger instance must be started before it becomes 
 functional and should be stopped when not needed.  Starting 
 and stoping the messenger can be achieved by calling the 
 start() or stop() method.
 
 Applications call the send methods to request messages to be delivered.
 When receiving is need, the application would need to register a listener
 as the callback interface to message receiving. 
 
 Status of messages sent can be queried by the application, or by 
 notification if a StatusListener has been registered with the system. 
 
 Payload/content of messages is define by the type 
 oracle.panama.messaging.common.Message. It abstracts content exchanged 
 between applications and their clients. The messages are typically untouched
 by the transport system.


 This section details about the Transport API explaining the majorconstructs
 and functionality available to customize the Transport System.
 Transport API is the client side messaging interface. Transport API is a 
 rich set of APIs which can be used for both sending and receiving. 
 In terms of sending, transport API provides some valued features, such as 
 messaging routing, status tracking.
 To receive messages, the application must register listening end points
 and a message callback listener to the transport system. An endpoint essentially 
 is in the form of an address such as a phone number. It identifies to the 
 transport system how message should be dispatched. When a message is received 
 for a targeted an address, it is dispatched to the listener associated with 
 a endpoint with a matching address.
 When a message delivery requested is submitted, the transport system performs
 analysis of the recipients and route them to the appropriate protocol drivers 
 for delivery.

 Destination analysis

   A single message can be delivered to multiple recipients of different 
 communication protocols. For example, one can send a meeting reminder to a few 
 people using SMS, and some other people to their email addresses. So before 
 routing messages to drivers, the transport must analysis and group recipients by 
 their delivery category. Typically, the transport system starts its internal 
 processing by analyzing all destinations and groups them accordingly.

 Message Routing

 To send a message, the transport system has to find a proper driver to do so. 
 The process of finding a proper driver is called message routing. The transport 
 system at a particular time may have many messaging servers and protocol drivers
 configured. Different driver instances may handle different category of messages.
 For example, a driver may be able to send SMS messages only. Another one may be
 able to send email and fax messages only. Therefore, the transport system has to
 use a driver with SMS capability to send SMS messages, a driver with email
 capability to send email messages. Sometimes, there may be more than one driver
 that can handle the same category of messages. For example, there could be more
 than two SMS drivers. One talks to ATT's SMSC, the other talks to Cingular's
 SMSC. The transport system needs to use ATT's SMS driver to send SMS messages
 to ATT's devices, and use Cingular's SMS driver to send SMS messages to
 Cingular's devices. All these decisions are made by the transport based on two sets
 of information. The first set is the sending criteria specified by the application,
 such as delivery type, speed, cost, encoding and so on. Out of all of the above, 
 the delivery type is required and can be specified in the class Destination. 
 The other set of information is provided by the set of available drivers. 
 The properties of the drivers are configured by the administrator, such as 
 driver speed, driver cost, encoding, delivery category. As we mentioned earlier, 
 routing is to find the best matching driver. Some properties much match, 
 for example, the delivery category,some of them if just the closest match, 
 for example, cost and speed.

 
 Providing hints to facilitate transport internal processing

 Applications can provide hints that help speed up the routing and analysis. 
 For example, if you specify "Email" as the delivery category of all recipients, 
 the transport will not have to look into each of the recipients to determine 
 what they are.
 In principal, the required parameter to deliver a 
 message(the Messenger.send() methods) is Destination and Message. All others, 
 SenderInfo, MessageInfo and DeviceInfo are optional. When they are specified, 
 they will be interpreted as hints that describe properties common to all 
 recipients. For example, if a DeviceInfo is specified and the getDeliveryType() 
 of this DeviceInfo instance returns DeliveryType.EMAIL.getName() then the 
 tranport will take it as a hint that all recipients are email addresses and no 
 destination analysis will be performed.
 Even for the required parameter say Destination, many attributes are optional.
 While the address is mandatory, the attribute of Driver is optional. If the value
 of Driver is not known, transport performs its routing algorithm to find a driver.
 If a driver is known, naming it as part of the Destination would avoid the 
 performing hit incurred by the routing algorithm.  Of course, a better way in this
 particular case is to implement the DriverFinder hook to fill in the
 driver name in a systematic manner so that the applications can focus purely
 on contents rather than low level details such as picking an appropriate  driver. 

 Receiving messages

 Messenger can only be used if you are developing an application that 
 will receive message, rather than sending messages only.
 
 In order to receive messages, your application needs to specify two addtional
 items:  EndPint and MessageListener.

 EndPoint essentially describe a transport type and an address(e.g. SMS 123456),
 it identifys what address your applicaion is interested in.  In the above example,
 registering endpoint for SMS 1234567 informs the transport that all messages 
 targeted for 1234567 over the SMS protocol belong to this applications. 
 One or more EndPoint can be registered for each application.

 MessageListener essentially is a callback interface.  One an instance of such
 interface is registered, messages belonging to this application will be devliered
 to the application using the callbacks defined in the MessageListener interface.
 
 
Fail-over is not implemented in the current version yet.
 If a non-null fail-over is specified, a
 not-implemented exception will be thrown.

Author:
jxiang

Field Summary
static int POST_RECEIVE
          constant for the type of hooks to be invoked after messages are received (delivered to the message listener)
static int POST_SEND
          constant for the type of hooks to be invoked after messages are sent
static int PRE_RECEIVE
          constant for the type of hooks to be invoked before messages are received (delivered to the message listener)
static int PRE_SEND
          constant for the type of hooks to be invoked before messages are sent

 

Method Summary
 void addEndPoint(EndPoint address)
          Add one address to the list of addresses this messenger listens to.
 void addEndPoints(EndPoint[] addresses)
          Add a list of addresses to the list of addresses this messenger listens to.
 void addGeneralHook(int type, GeneralHook hook)
          Add a specified type of general hook of the messenger.
 EndPoint[] getEndPoints()
          Get the list of addresses this messenger listens to.
 GeneralHook[] getGeneralHooks(int type)
          Get all the specified type of general hooks of the messenger.
 java.lang.String getName()
          Get the name of the messenger.
 int getNumOfReceivingThreads()
          Get the number of listening threads.
 Status getStatus(java.lang.String mid)
          Get the sending status of a message.
 Status[] getStatus(java.lang.String[] mids)
          Get the sending status of messages.
 boolean isStarted()
          Check if the messenger is started.
 void removeAllEndPoints()
          Remove all addresses the messenger listens to.
 void removeEndPoint(EndPoint address)
          Remove one address from the list of addresses the messenger listens to.
 void removeEndPoints(EndPoint[] addresses)
          Remove a list of addresses from the list of addresses the messenger listens to.
 void removeErrorListener()
          Unregister the error listener if any is registered.
 void removeGeneralHook(int type, GeneralHook hook)
          Remove a specified type of general hook of the messenger.
 void removeGeneralHooks(int type)
          Remove all general hooks of the messenger of a specified type.
 void removeMessageListener()
          Unregister the message listener if any is registered.
 void removeStatusListener()
          Unregister the status listener if any is registered.
 java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo[] dis, MessageInfo mi, Message message, java.lang.String[] failover)
          Send a message to a list of addresses with device info hint and message info hint.
 java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo[] dis, Message message, java.lang.String[] failover)
          Send a message to a list of addresses with device info hint.
 java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo di, MessageInfo mi, Message message, java.lang.String[] failover)
          Send a message to a list of addresses with device info hint and message info hint.
 java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo di, Message message, java.lang.String[] failover)
          Send a message to a list of addresses with device info hint.
 java.lang.String[] send(Destination[] devices, SenderInfo[] sis, MessageInfo mi, Message message, java.lang.String[] failover)
          Send a message to a list of addresses with message into hint.
 java.lang.String[] send(Destination[] devices, SenderInfo[] sis, Message message, java.lang.String[] failover)
          Send a message to a list of addresses.
 java.lang.String send(Destination device, SenderInfo si, Message message, java.lang.String[] failover)
          Send a message to one receipient.
 java.lang.String send(Destination device, SenderInfo si, java.lang.String mid, java.lang.String[] failover)
          Re-send a message to one receipient.
 void setErrorListener(StatusListener listener)
          Set the error listener of this messenger.
 void setMessageListener(MessageListener listener)
          Set the message listener of this messenger.
 void setNumOfReceivingThreads(int threads)
          Set the number of listening threads.
 void setStatusListener(StatusListener listener)
          Set the status listener of this messenger.
 void start()
          Start the messenger.
 void stop()
          Stop the messenger.

 

Field Detail

PRE_SEND

public static final int PRE_SEND
constant for the type of hooks to be invoked before messages are sent
See Also:
Constant Field Values

POST_SEND

public static final int POST_SEND
constant for the type of hooks to be invoked after messages are sent
See Also:
Constant Field Values

PRE_RECEIVE

public static final int PRE_RECEIVE
constant for the type of hooks to be invoked before messages are received (delivered to the message listener)
See Also:
Constant Field Values

POST_RECEIVE

public static final int POST_RECEIVE
constant for the type of hooks to be invoked after messages are received (delivered to the message listener)
See Also:
Constant Field Values
Method Detail

getName

public java.lang.String getName()
Get the name of the messenger. This method returns the name used when the messenger was created, or the unique name assigned to it if name was not provided in creation.
Returns:
the name of the messenger.

start

public void start()
           throws TransportException
Start the messenger. Each instance of messager must be started before it functions. Calling start mutiple times is OK with the effect of call start just once. However the number of start called is counted and the instance will not stop until a matching number of stop is called. Calling start after it is actually stopped re-starts the messenger.
Throws:
TransportException - if failed to start.

stop

public void stop()
          throws TransportException
Stop the messenger. Calling stop a matching number of times as start is called actually stops the messenger instance. Calling stop on a not yet started messenger instance has no effect, it does not prevent the next start call from starting the messenger.
Throws:
TransportException - if an error detected.

isStarted

public boolean isStarted()
Check if the messenger is started.
Returns:
true if it is started, false otherwise.

setNumOfReceivingThreads

public void setNumOfReceivingThreads(int threads)
Set the number of listening threads. Listening threads are used to deliver messages or status received. A defalut configuration number is set to 2 for the listening threads.
Parameters:
threads - the number of listening threads.

getNumOfReceivingThreads

public int getNumOfReceivingThreads()
Get the number of listening threads.
Returns:
the number of listening threads.

send

public java.lang.String send(Destination device,
SenderInfo si,
                             java.lang.String mid,
                             java.lang.String[] failover)
                      throws TransportException
Re-send a message to one receipient. This request to re-send a message to a single recipient, specify the id of the original message, the new recipient and sender infomation.
Parameters:
device - the new destination device.
si - the new sender information.
mid - the id of the original message.
failover - the fail-over delivery types(not yet implemented).
Throws:
TransportException - if an error detected.

send

public java.lang.String send(Destination device,
SenderInfo si,
Message message,
                             java.lang.String[] failover)
                      throws TransportException
Send a message to one receipient. This request to send a message to a single recipient, specify the content, recipient and sender.
Parameters:
device - the destination device.
si - the sender information.
message - the message.
failover - the fail-over delivery types(not yet implemented).
Throws:
TransportException - if an error detected.

send

public java.lang.String[] send(Destination[] devices,
SenderInfo[] sis,
Message message,
                               java.lang.String[] failover)
                        throws TransportException
Send a message to a list of addresses. This method request a message be delivered. Multiple recipients Are allowed. You can also optionally provide multiple senders. Multiple senders are necessary when the recipients are of multiple transport types. For example, you specified a@b.c as sender for email. But that won't make sense for the SMS recipients, you might want to provide a SMS address as the sender for your SMS recipients. Sender info is optional. When they are indeed specified, only one sender is allowed for one transport type. If multiple of them are provided here, the first one prevails.
Parameters:
devices - the destination devices.
sis - the sender information.
message - the message.
failover - the fail-over delivery types.
Throws:
TransportException - if an error detected.

send

public java.lang.String[] send(Destination[] devices,
SenderInfo[] sis,
DeviceInfo di,
Message message,
                               java.lang.String[] failover)
                        throws TransportException
Send a message to a list of addresses with device info hint.
Parameters:
devices - the destination devices.
sis - the sender information.
di - the device information, which overrides that of devices.
message - the message.
failover - the fail-over delivery types.
Throws:
TransportException - if an error detected.

send

public java.lang.String[] send(Destination[] devices,
SenderInfo[] sis,
DeviceInfo[] dis,
Message message,
                               java.lang.String[] failover)
                        throws TransportException
Send a message to a list of addresses with device info hint.
Parameters:
devices - the destination devices.
sis - the sender information.
dis - the device information, which overrides that of devices.
message - the message.
failover - the fail-over delivery types.
Throws:
TransportException - if an error detected.

send

public java.lang.String[] send(Destination[] devices,
SenderInfo[] sis,
MessageInfo mi,
Message message,
                               java.lang.String[] failover)
                        throws TransportException
Send a message to a list of addresses with message into hint.
Parameters:
devices - the destination devices.
sis - the sender information.
mi - the message info, which overrides that of devices.
message - the message.
failover - the fail-over delivery types.
Throws:
TransportException - if an error detected.

send

public java.lang.String[] send(Destination[] devices,
SenderInfo[] sis,
DeviceInfo di,
MessageInfo mi,
Message message,
                               java.lang.String[] failover)
                        throws TransportException
Send a message to a list of addresses with device info hint and message info hint.
Parameters:
devices - the destination devices.
sis - the sender information.
di - the device information, which overrides that of devices.
mi - the message info, which overrides that of devices.
message - the message.
failover - the fail-over delivery types.
Throws:
TransportException - if an error detected.

send

public java.lang.String[] send(Destination[] devices,
SenderInfo[] sis,
DeviceInfo[] dis,
MessageInfo mi,
Message message,
                               java.lang.String[] failover)
                        throws TransportException
Send a message to a list of addresses with device info hint and message info hint.
Parameters:
devices - the destination devices.
sis - the sender information.
dis - the device information, which overrides that of devices.
mi - the message info, which overrides that of devices.
message - the message.
failover - the fail-over delivery types.
Throws:
TransportException - if an error detected.

getStatus

public Status getStatus(java.lang.String mid)
                 throws TransportException
Get the sending status of a message.
Parameters:
mid - the id of the message.
Returns:
the status.
Throws:
TransportException - if an error detected.

getStatus

public Status[] getStatus(java.lang.String[] mids)
                   throws TransportException
Get the sending status of messages.
Parameters:
mids - the ids of these messages.
Returns:
the statuses.
Throws:
TransportException - if an error detected.

setMessageListener

public void setMessageListener(MessageListener listener)
Set the message listener of this messenger. Registering a MessageListener is optional and is only needed if the appliation is to receive messages. If needed to register a MessageListener the call must be made before the messenger is started(by calling the start() method). If called multiple times(before start()) the last call prevails.
Parameters:
listener - the message listener.

removeMessageListener

public void removeMessageListener()
Unregister the message listener if any is registered.

setStatusListener

public void setStatusListener(StatusListener listener)
Set the status listener of this messenger. Registering a StatusListener is optional and is only needed if the application is interested for status of the messages sent through callback. If needed to register a StatusListener, the call must be made before the messenger is started(by calling the start() method). If called multiple times(before start()) the last call prevails.
Parameters:
listener - the status listener.

removeStatusListener

public void removeStatusListener()
Unregister the status listener if any is registered.

setErrorListener

public void setErrorListener(StatusListener listener)
Set the error listener of this messenger.
Parameters:
listener - the error listener.

removeErrorListener

public void removeErrorListener()
Unregister the error listener if any is registered.

getEndPoints

public EndPoint[] getEndPoints()
Get the list of addresses this messenger listens to.
Returns:
the end points.

addEndPoint

public void addEndPoint(EndPoint address)
Add one address to the list of addresses this messenger listens to.
Parameters:
address - the end point to add.

addEndPoints

public void addEndPoints(EndPoint[] addresses)
Add a list of addresses to the list of addresses this messenger listens to.
Parameters:
addresses - the end points to add.

removeEndPoint

public void removeEndPoint(EndPoint address)
Remove one address from the list of addresses the messenger listens to.
Parameters:
address - the end point to remove.

removeEndPoints

public void removeEndPoints(EndPoint[] addresses)
Remove a list of addresses from the list of addresses the messenger listens to.
Parameters:
addresses - the end points to remove.

removeAllEndPoints

public void removeAllEndPoints()
Remove all addresses the messenger listens to.

getGeneralHooks

public GeneralHook[] getGeneralHooks(int type)
Get all the specified type of general hooks of the messenger.
Parameters:
type - the general hook type.
Returns:
a list of general hooks.

addGeneralHook

public void addGeneralHook(int type,
GeneralHook hook)
Add a specified type of general hook of the messenger.
Parameters:
type - the general hook type.
hook - a general hook.

removeGeneralHook

public void removeGeneralHook(int type,
GeneralHook hook)
Remove a specified type of general hook of the messenger.
Parameters:
type - the general hook type.
hook - a general hook.

removeGeneralHooks

public void removeGeneralHooks(int type)
Remove all general hooks of the messenger of a specified type.
Parameters:
type - the general hook type.

Oracle Application Server Wireless Java API Reference
B10400-01

Copyright © 2003 Oracle Corporation. All Rights Reserved.