|
Oracle Application Server Wireless Java API Reference B14043-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 |
public static final int POST_RECEIVE
public static final int POST_SEND
public static final int PRE_RECEIVE
public static final int PRE_SEND
Method Detail |
public void addEndPoint(EndPoint address)
address
- the end point to add.public void addEndPoints(EndPoint[] addresses)
addresses
- the end points to add.public void addGeneralHook(int type, GeneralHook hook)
type
- the general hook type.hook
- a general hook.public EndPoint[] getEndPoints()
public GeneralHook[] getGeneralHooks(int type)
type
- the general hook type.public java.lang.String getName()
public int getNumOfReceivingThreads()
public Status getStatus(java.lang.String mid) throws TransportException
mid
- the id of the message.TransportException
- if an error detected.public Status[] getStatus(java.lang.String[] mids) throws TransportException
mids
- the ids of these messages.TransportException
- if an error detected.public boolean isStarted()
public void removeAllEndPoints()
public void removeEndPoint(EndPoint address)
address
- the end point to remove.public void removeEndPoints(EndPoint[] addresses)
addresses
- the end points to remove.public void removeErrorListener()
public void removeGeneralHook(int type, GeneralHook hook)
type
- the general hook type.hook
- a general hook.public void removeGeneralHooks(int type)
type
- the general hook type.public void removeMessageListener()
public void removeStatusListener()
public java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo[] dis, MessageInfo mi, Message message, java.lang.String[] failover) throws TransportException
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.TransportException
- if an error detected.public java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo[] dis, Message message, java.lang.String[] failover) throws TransportException
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.TransportException
- if an error detected.public java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo di, MessageInfo mi, Message message, java.lang.String[] failover) throws TransportException
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.TransportException
- if an error detected.public java.lang.String[] send(Destination[] devices, SenderInfo[] sis, DeviceInfo di, Message message, java.lang.String[] failover) throws TransportException
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.TransportException
- if an error detected.public java.lang.String[] send(Destination[] devices, SenderInfo[] sis, MessageInfo mi, Message message, java.lang.String[] failover) throws TransportException
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.TransportException
- if an error detected.public java.lang.String[] send(Destination[] devices, SenderInfo[] sis, Message message, java.lang.String[] failover) throws TransportException
devices
- the destination devices.sis
- the sender information.message
- the message.failover
- the fail-over delivery types.TransportException
- if an error detected.public java.lang.String send(Destination device, SenderInfo si, Message message, java.lang.String[] failover) throws TransportException
device
- the destination device.si
- the sender information.message
- the message.failover
- the fail-over delivery types(not yet implemented).TransportException
- if an error detected.public java.lang.String send(Destination device, SenderInfo si, java.lang.String mid, java.lang.String[] failover) throws TransportException
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).TransportException
- if an error detected.public void setErrorListener(StatusListener listener)
listener
- the error listener.public void setMessageListener(MessageListener listener)
listener
- the message listener.public void setNumOfReceivingThreads(int threads)
threads
- the number of listening threads.public void setStatusListener(StatusListener listener)
listener
- the status listener.public void start() throws TransportException
TransportException
- if failed to start.public void stop() throws TransportException
TransportException
- if an error detected.
|
Oracle Application Server Wireless Java API Reference B14043-01 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |