oracle.panama.messaging.transport
Interface MessagingController

public interface MessagingController

 This interface represents the entry point to the Transport messaging API.
 
 The MessagingController is the entry point to the interface offered
 by the transport system for messaging.  This interface is designed 
 for the use of content providers in building messaging based applications.  
 (please see TransportLocator for an overview of the transport system).

 With the messaging interface, two way applications, both sending and receiving
 messages, can be built without having to worry about particular communication 
 protocols(such as SMS, voice, email) at all.  All is needed is a description of 
 the recipient, such as "SMS 1234567".

Author:

jxiang

Method Summary

java.lang.String[]	getDeliveryTypes() Get all currently supported delivery types.
DriverInfo[]	getDriverInfos() Get information about drivers currently configured.
Messenger	getMessenger() Create a new messenger instance without specifying a name.
Messenger	getMessenger(java.lang.String name) Get a named messenger instance, create one if not exists.
java.lang.String	getVersion() Get the version of this transport system.

Method Detail

getVersion

public java.lang.String getVersion()

Get the version of this transport system.

Returns:

the transport version.

getMessenger

public Messenger getMessenger(java.lang.String name)

Get a named messenger instance, create one if not exists. Messenger represents the main interface for messaging operatios such as send and receive. Name is optional when requesting for a Messenger. When name is not specified a new instance with an internally assigned unique name is created. Hence it would save resources if messenger instances can be reused by referring to its name. A messenger instance needs to be started before it can provide service, and should be stopped when not needed.

Parameters:

name - the name of the messenger.

Returns:

the named messenger instance.

getMessenger

public Messenger getMessenger()

Create a new messenger instance without specifying a name. A messenger always has a name. If no name is specified by the user, a unique name will be assigned internally. Creating two messengers with no name really do create two instances of the messenger. It's more resource conserving to reuse another instance, if possible, or create one with name and obtain it elsewhere by referring to its name.

Returns:

a newly created messenger instance.

getDriverInfos

public DriverInfo[] getDriverInfos()
                            throws TransportException

 Get information about drivers currently configured.

 This API is for advanced users.  Driver info can be used
 to control the routing of messages.  

 Normally the routing and picking a driver to deliver a 
 message is performed by the transport system. However, if 
 an application wants more control it can specify infomation
 used by the transport so as to influence the routing decision.
 For example, when requesting to send a message, specifying a carrier 
 narrows the set of driver the transport picks to those that support
 carrier matching the one specified; specifying a driver name completely 
 bypasses the tranports's routing logic.
 
 Please see the sending API for more info.

Returns:

a list of supported driverers' information.

Throws:

TransportException - if the transport failed to load all driver information.

getDeliveryTypes

public java.lang.String[] getDeliveryTypes()
                                    throws TransportException

Get all currently supported delivery types. While appliactions programming against the messaging APIs need not be concerned about the actual communication protocols, it might need to know what protocols are being supported at that particular moment, for example, if SMS and Email drivers are configured, these two types will be returned. This info could be useful for example to construct a UI listing only protocols currently have support for so that the application does not accept recipients which can not be handled by the underlying system.

Returns:

a list of supported delivery types as defined in oracle.panama.messaging.common.TransportType

Throws:

TransportException - if the transport failed to load all supported delivery types.