javax.telephony.media.messaging
Interface NamedService

All Superinterfaces:

java.util.EventListener, MediaConstants, MediaListener, MessageConstants

public interface NamedService

extends MediaListener, MessageConstants

Send and receive messages on a messaging connection.

A NamedService represents a messaging connection between the Service supplier and the Service subscriber. The supplier creates one end of the connection using registerService(); the subscriber creates the other end using openNamedService(). When a subscriber opens the NamedService, the supplier gets an onServiceOpened() notification (eventID equals ev_ServiceOpened). That event contains a NamedService that represents the subscriber to the provider.

Either end of a message connection may send a Request or an Event to the other end. If a Request is received, it must be replied to using ServiceRequest.reply().

Either end may close the connection. The other party gets an onServiceClosed() notification (eventID equals ev_ServiceClosed).

Note: ServiceEvents are dispatched to the NamedServiceListener that is established when the NamedService is created.

Since:

JTAPI-1.4

Fields inherited from interface javax.telephony.media.messaging.MessageConstants

e_NotFound, e_NotSupported, ev_Close, ev_OpenNamedService, ev_RegisterService, ev_ServiceClosed, ev_ServiceOpened, ev_UnregisterService, k_Error, k_EventData, k_Payload, k_Qualifier, k_ServiceName, k_Status, k_SubError, v_Null

Fields inherited from interface javax.telephony.media.MediaConstants

e_OK, q_Duration, q_Standard, q_Stop

Method Summary

void	addListener(java.util.EventListener listener) Add a Listener for Events dispatched by this NamedService.
Async_ServiceEvent	async_close() Async form of close.
Async_ServiceEvent	async_request(Symbol cmdID, java.util.Dictionary payload) Async form of request.
void	close() Terminate messaging connection between Service and User.
boolean	isOpen() Return true if this NamedService is open.
void	removeListener(java.util.EventListener listener) Remove an EventListener from this NamedService.
ServiceEvent	request(Symbol cmdID, java.util.Dictionary payload) Send a request on this message connection, and wait for the reply.
void	sendEvent(Symbol eventID, java.util.Dictionary payload) Send a non-transactional event on this message connection.

Method Detail

request

public ServiceEvent request(Symbol cmdID,
                            java.util.Dictionary payload)
                     throws ServiceException

Send a request on this message connection, and wait for the reply.

Maintains a transaction waiting for a reply. When the reply is returned, the transaction is done and Async_NamedServiceListener.onRequestDone is invoked

Note: If a reply is not expected, consider using sendEvent() instead.

Note:On the other end, request messages are delivered to NamedServiceLisetner.onServiceRequest

Parameters:

cmdID - the event Symbol to identify the request

the - payload of the Request.

Returns:

an ServiceEvent that is isDone().

Throws:

ServiceClosedException - if this service is closed.

ServiceRequestException - if request returns an Exception

async_request

public Async_ServiceEvent async_request(Symbol cmdID,
                                        java.util.Dictionary payload)
                                 throws ServiceException

Async form of request. When the a reply is returned, the transaction is done and Async_NamedServiceListener.onRequestDone is invoked

Parameters:

cmdID - the event Symbol to identify the request

the - payload of the Request.

Returns:

an Async_ServiceEvent.

Throws:

ServiceClosedException - if this service is closed.

See Also:

Async_NamedServiceListener

sendEvent

public void sendEvent(Symbol eventID,
                      java.util.Dictionary payload)
               throws ServiceException

Send a non-transactional event on this message connection.

Note:This method does not wait for any reply.

Note:On the other end, event messages are delivered to NamedServiceLisetner.onServiceEvent

Parameters:

eventID - the event Symbol to identify the event

the - payload of the Event.

Throws:

ServiceClosedException - if this service is closed.

isOpen

public boolean isOpen()

Return true if this NamedService is open.

A NamedService is open until it has been close by either end.

Returns:

true if this NamedService is open.

close

public void close()

Terminate messaging connection between Service and User. Release the subscriber from the provider. Send ev_ServiceClosed event to other end.

async_close

public Async_ServiceEvent async_close()

Async form of close.

addListener

public void addListener(java.util.EventListener listener)

Add a Listener for Events dispatched by this NamedService.

To get asynchronous notification of ServiceEvents, addListener(NamedServiceListener)

Note: the NamedServiceListener specified when the NamedService is created is automatically added.

Note: This method accepts any java.util.EventListener but ServiceEvents are delivered only to a NamedServiceListener. 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:

NamedServiceListener, Async_NamedServiceListener

removeListener

public void removeListener(java.util.EventListener listener)

Remove an EventListener from this NamedService.

See Also:

NamedServiceListener, Async_NamedServiceListener