javax.telephony.media.messaging
Interface MessagingService

public interface MessagingService

Holds the methods that extend MediaProvider for Service registry and Message delivery.

The MessagingService allows cooperating applications to send commands and event to each other.

Since:

JTAPI-1.4

Method Summary

void	addListener(java.util.EventListener listener) Add a Listener for Events dispatched by this MessagingService.
Async_ServiceEvent	async_close(java.lang.String serviceName) Async form of close.
Async_ServiceEvent	async_openNamedService(java.lang.String serviceName, NamedServiceListener listener, java.util.Dictionary attributes) Async form of openNamedService.
Async_ServiceEvent	async_registerService(java.lang.String serviceName, NamedServiceListener listener, java.util.Dictionary attributes) Async form of registerService.
Async_ServiceEvent	async_unregisterService(java.lang.String serviceName) Async form of unregisterService.
void	close(java.lang.String serviceName) Unregister the given serviceName and close all NamedService connections to that serviceName.
NamedService	openNamedService(java.lang.String serviceName, NamedServiceListener listener, java.util.Dictionary attributes) Find a service and establish a messaging connection.
void	registerService(java.lang.String serviceName, NamedServiceListener listener, java.util.Dictionary attributes) Register this MediaProvider as a NamedService with the Server.
void	removeListener(java.util.EventListener listener) Remove an EventListener from this NamedService.
void	unregisterService(java.lang.String serviceName) Unregister the serviceName, preventing further openings.

Method Detail

openNamedService

public NamedService openNamedService(java.lang.String serviceName,
                                     NamedServiceListener listener,
                                     java.util.Dictionary attributes)
                              throws ServiceException

Find a service and establish a messaging connection.

When the connection is closed (by any of releaseService(), unregisterService(), or session death), the other end is notified via onServiceClosed().

Parameters:

serviceName - the String name to be registered

listener - for Events and Requests from the service.

attributes - a Dictionary to restrict the choice of providers that supply serviceName

Throws:

NotRegisteredException - if name is not registered

async_openNamedService

public Async_ServiceEvent async_openNamedService(java.lang.String serviceName,
                                                 NamedServiceListener listener,
                                                 java.util.Dictionary attributes)
                                          throws ServiceException

Async form of openNamedService.

Parameters:

serviceName - the String name to be registered

listener - for Events and Requests from the service.

attributes - a Dictionary to restrict the choice of providers that supply serviceName Async form of openNamedService.

Returns:

an Async_ServiceEvent object

Throws:

ServiceException - if serviceName cannot be opened.

registerService

public void registerService(java.lang.String serviceName,
                            NamedServiceListener listener,
                            java.util.Dictionary attributes)
                     throws ServiceException

Register this MediaProvider as a NamedService with the Server. Other applications can find this service using openNamedService().

The attributes are stored as part of the registration. The supplied attributes restrict when openNamedService will find this registered service. For this service to be found, the attributes supplied to openNamedService must be a superset of the attributes supplied to registerService.

A NamedService is created in the service supplier when another application (the service subscriber) connects to this serviceName (using openNamedService). The given NamedServiceListener is added to each such NamedService and is used for two purposes:

• The listener receives onServiceOpened() and onServiceClosed() notifications for each NamedService created on this serviceName.
• The listener receives onServiceEvent() and onServiceRequest() notfications for each message delivered to the NamedService.

Note: other listeners can be added to the NamedService and this initial listener can be removed.

Parameters:

serviceName - the String by which this NamedService can be opened.

listener - a NamedServiceListener for new message connections.

attributes - a Dictionary of selection attributes

Throws:

NotRegisteredException - if could not register

See Also:

NamedServiceListener

async_registerService

public Async_ServiceEvent async_registerService(java.lang.String serviceName,
                                                NamedServiceListener listener,
                                                java.util.Dictionary attributes)
                                         throws ServiceException

Async form of registerService.

Parameters:

serviceName - the String by which this NamedService can be opened.

listener - a NamedServiceListener for new message connections.

attributes - a Dictionary of selection attributes

Returns:

an Async_ServiceEvent object

Throws:

ServiceException - if serviceName cannot be registered.

unregisterService

public void unregisterService(java.lang.String serviceName)
                       throws ServiceException

Unregister the serviceName, preventing further openings.

Parameters:

serviceName - the String by which this NamedService was registered.

Throws:

ServiceException - if serviceName cannot be unregistered.

async_unregisterService

public Async_ServiceEvent async_unregisterService(java.lang.String serviceName)
                                           throws ServiceException

Async form of unregisterService.

Parameters:

serviceName - the String by which this NamedService was registered.

close

public void close(java.lang.String serviceName)
           throws ServiceException

Unregister the given serviceName and close all NamedService connections to that serviceName.

Parameters:

serviceName - the String by which this NamedService can be opened.

Throws:

ServiceException - if serviceName cannot be closed.

async_close

public Async_ServiceEvent async_close(java.lang.String serviceName)
                               throws ServiceException

Async form of close.

Parameters:

serviceName - the String by which this NamedService can be opened.

Returns:

an Async_ServiceEvent object

Throws:

ServiceException - if serviceName cannot be closed.

addListener

public void addListener(java.util.EventListener listener)

Add a Listener for Events dispatched by this MessagingService.

To get asynchronous notification of MessagingService method completion, use
addListener(Async_MessagingServiceListener)

Note: This method accepts any java.util.EventListener but ServiceEvents are delivered only to a Async_MessagingServiceListener. Unless/until the MessagingService is extended (for example, by a JtapiPeer vendor) to create other classes of events, other Listeners are not invoked.

See Also:

Async_MessagingServiceListener

removeListener

public void removeListener(java.util.EventListener listener)

Remove an EventListener from this NamedService.

See Also:

Async_MessagingServiceListener