9 Parlay X Web Services Multimedia Messaging API

This chapter describes support for the Parlay X 2.1 Multimedia Messaging Web Services interfaces for developing applications. The Web service functions as a Messaging Agent which can send, receive, and listen to notifies on behalf of the users of the Web service. This chapter contains the following sections:

Section 9.1, "Introduction"
Section 9.2, "Installing the Web Services"
Section 9.3, "Configuring Web Services"
Section 9.4, "Messaging Web Services Interface Descriptions"
Section 9.5, "Using the Messaging Web Services Interfaces"

9.1 Introduction

The following sections describe the semantics of each of the supported operations along with implementation-specific details for the Parlay X Gateway.

The product support the interfaces defined in the Parlay X 2.1 Multimedia Messaging Web Services specification.

9.2 Installing the Web Services

The Web services are packaged as a standard .ear file and can be deployed the same as any other Web services through Admin Console. The .ear file contains three .war files that implement the three interfaces. The Web services use the Oracle SDP Platform, Client and Presence Commons shared libraries.

9.3 Configuring Web Services

There are four mbean attributes that are configurable for the Messaging Web service:

SIPOutboundProxy - SipURI of the outbound proxy for SIP message. Empty string means no outbound proxy. Currently, only support IP address. For example, sip:127.0.0.1:5060; lr;transport=tcp.
SessionTimeout - Set the time in seconds after which HTTP sessions time out. Data for all timed out sessions is discarded.
MessageLifetime - Set the time in seconds after which messages expire from the message store. Setting this to 0 causes messages to be kept in the store indefinitely (never expire). Messages stay in the message store for at most MessageLifetime + MessageScanPeriod seconds. Setting this attribute has immediate effect (for instance, reducing the value could cause some messages to be immediately expired if they are older than the lifetime).
MessageScanPeriod - Set the period in seconds for scanning for and deleting expired messages. Setting this to 0 disables scanning. Setting this attribute has immediate effect.

9.4 Messaging Web Services Interface Descriptions

The messaging Web services consist of four interfaces:

SendMessage: Use these methods to send messages (Table 9-1).
ReceiveMessage: Use these methods to receive message content (Table 9-2).
MessageNotificationManager: Use these methods to manage which users are notified when messages are received through the Web service (Table 9-3).

MessageNotification: The client callback defined in this interface is used to send notifications (Table 9-4).

Table 9-1 SendMessage Interface

Operation	Description
sendMessage	Sends a SIP MESSAGE to designated user(s). Returns an outgoing message ID.
getMessageDeliveryStatus	Returns a set of delivery statuses for each recipient of an outgoing message sent through sendMessage.

Table 9-2 ReceiveMessage Interface

Operation	Description
getMessage	Receives an incoming message.
getMessageURIs	Not implemented.
getReceivedMessages	Returns a set of incoming messages for a given user.

Table 9-3 MessageNotificationManager Interface

Operation	Description
startMessageNotification	Starts message notification at a given endpoint for a user. Notifies endpoint when messages are received for user.
stopMessageNotification	Stops message notification at an endpoint for a user.

Table 9-4 MessageNotification Interface

Operation	Description
notifyMessageDeliveryReceipt	Client callback invoked to notify the user of a message's final delivery status.
notifyMessageReception	Client callback invoked to notify the client that the user received a message.

9.5 Using the Messaging Web Services Interfaces

This section describes how to use each of the operations in the interfaces, and includes code examples. The following requirements apply:

An argument of type "StringSipURI" means that the argument is a String but must be a valid URI with "sip" or "sips" scheme, otherwise a ServiceException gets thrown. Refer to the Oracle Fusion Middleware WebLogic Communication Services API Reference for additional documentation on the content indirection API.

9.5.1 Interface SendMessage, Operation: sendMessage

This operation sends a SIP MESSAGE to designated user(s). Returns an outgoing message ID.

Table 9-5 Interface: SendMessage, Operation: sendMessage

Argument	Type	Required	Description
addresses	List<StringSipURI>	yes	Destination address(es) for this message.
senderAddress	StringSipURI	yes	Message sender address.
subject	String	no	Message subject. If there is no plain text attachment with the request, the subject is treated as the message content.
priority	MessagePriority	no	This value is ignored.
charging	ChargingInformation	no	This value is ignored.
receiptRequest	SimpleReference	no	Defines the application endpoint, interfaceName, and correlator that is used to notify the application of the final delivery status of the message.
Return Value	Type		Description
messageIdentifier	String		This identifier is used in a getMessageDeliveryStatus operation invocation to get the delivery status of sent messages.

9.5.1.1 Code Example

Map<String, Object> params = new HashMap<String, Object>();
params.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    "http://webservicehost:7001/sendMessageEndpoint");
SendMessageClient sendMsgClient = new SendMessageClient(params);
List<String> recipients = new ArrayList<String>();
recipients.add("sip:receiver@example.com");
String correlator = UUID.randomUUID().toString();
SimpleReference ref = new SimpleReference();
ref.setCorrelator(correlator);
ref.setEndpoint("http://clienthost:8080/notificationEndpoint");
ref.setInterface("MessageNotification");
String msgID = sendMsgClient.sendMessage(recipients,
    "sip:sender@example.com", "message content",
    MessagePriority.DEFAULT, null, ref);

9.5.2 Interface SendMessage, Operation: getMessageDeliveryStatus

This operation returns a set of delivery statuses for each recipient of an outgoing message sent via sendMessage. Call this operation with the ID returned by sendMessage.

Table 9-6 Interface SendMessage, Operation: getMessageDeliveryStatus

Argument	Type	Required	Description
messageIdentifier	String	yes	Identifier related to the delivery status request.
Return Value	Type		Description
status	List<DeliveryInformation>		A list of status of the messages that were previously sent. Each item represents a sent message, its destination address, and its delivery status.

9.5.2.1 Code Example

String msgID = sendMsgClient.sendMessage(...);
List<DeliveryInformation> infoList =
    sendMsgClient.getMessageDeliveryStatus(msgID);
for (DeliveryInformation info : infoList) {
    System.out.println(“recipient: “ + info.getAddress());
    System.out.println(“status: “ + info.getDeliveryStatus());
}

9.5.3 Interface MessageNotificationManager, Operation: startMessageNotification

This operation starts message notification at a given endpoint for a user. This means that when messages are received for this user, the client callback notifyMessageReception is invoked at the given MessageNotification endpoint. This also means that the web service stores received messages for this user, and the received messages can be obtained through the ReceiveMessage interface.

Table 9-7 Interface MessageNotificationManager, Operation: startMessageNotification

Argument	Type	Required	Description
reference	SimpleReference	yes	Defines the application endpoint, interfaceName, and correlator that is used to notify the application when a message is received.
messageServiceActivationNumber	StringSipURI	yes	The application is notified when messages are received for this SIP address.
criteria	String	no	This value is ignored.

9.5.3.1 Code Example

Map<String, Object> params = new HashMap<String, Object>();
params.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    "http://webservicehost:7001/msgNotiMgrEndpoint");
MessageNotificationManagerClient msgNotiMgrClient =
    new MessageNotificationManagerClient(params);
SimpleReference ref = new SimpleReference();
String correlator = UUID.randomUUID().toString()
ref.setCorrelator(correlator);
ref.setEndpoint("http://clienthost:8080/notificationEndpoint");
ref.setInterface("MessageNotification");
msgNotiMgrClient.startMessageNotification(ref,
    "sip:receiver@example.com","dummy_criteria_ignored");

9.5.4 Interface MessageNotificationManager, Operation: stopMessageNotification

This operation stops message notification at an endpoint for a user. If a user no longer has notification endpoints, all received messages for that user are no longer stored.

Table 9-8 Interface MessageNotificationManager, Operation: stopMessageNotification

Argument	Type	Required	Description
correlator	String	yes	The correlator associated with an invocation of the startMessageNotification operation.

9.5.4.1 Code Example

msgNotiMgrClient.stopMessageNotification(correlator);

9.5.5 Interface ReceiveMessage, Operation: getReceivedMessages

This operation returns a set of incoming messages for a given user. Messages may only be received after notification has been enabled by invoking the startMessageNotifcation operation in the MessageNotificationManager interface.

Table 9-9 Interface ReceiveMessage, Operation: getReceivedMessages

Argument	Type	Required	Description
registrationIdentifier	StringSipURI	yes	The recipient SIP address for incoming messages.
priority	MessagePriority	no	This value is ignored.
Return Value	Type		Description
references	List<MessageReference>		A list of messages received for this user. Each item may either have a message identifier or message content, but is not guaranteed to have both an identifier and content.

9.5.5.1 Code Example

Map<String, Object> params = new HashMap<String, Object>();
params.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    "http://webservicehost:7001/receiveMessageEndpoint");
ReceiveMessageClient recvMsgClient = new ReceiveMessageClient(params);
List<MessageReference> msgs =
    recvMsgClient.getReceivedMessages("sip:receiver@example.com",
    MessagePriority.DEFAULT);
for (MessageReference ref : msgs) {
    System.out.println("to: "+ref.getMessageServiceActivationNumber();
    System.out.println("from: "+ref.getSenderAddress());
    System.out.println("subject: "+ref.getSubject());
    String id = ref.getMessageIdentifier();
    if (id == null || id.isEmpty()) {
        System.out.println("message: "+ref.getMessage());
    } else {
        System.out.println("ID: "+id);
    }
}

9.5.6 Interface: ReceiveMessage, Operation: getMessage

This operation receives an incoming message as an attachment. Messages may only be received after notification has been enabled by invoking the startMessageNotifcation operation in the MessageNotificationManager interface.

Table 9-10 Oracle WebLogic Communication ServicesInterface: ReceiveMessage, Operation: getMessage

Argument	Type	Required	Description
messageIdentifier	String	yes	A string identifying the incoming message. This string is obtained either from the notifyMessageReception callback, or the getReceivedMessages operation invocation.
Return Value	Type		Description
n/a	n/a		After invoking the getMessage operation, the message content is stored in an attachment of type DataHandler.

9.5.6.1 Code Example

List<MessageReference> msgs =
    recvMsgClient.getReceivedMessages("sip:receiver@example.com",
    MessagePriority.DEFAULT);
for (MessageReference ref : msgs) {
    String id = ref.getMessageIdentifier();
    String msgContent;
    if (id == null || id.isEmpty()) {
        msgContent = ref.getMessage();
    } else {
        System.out.println("ID: " + id);
        recvMsgClient.getMessage(id);
        DataHandler dh = recvMsgClient.getAttachment();
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        BufferedOutputStream out = new BufferedOutputStream(baos);
        dh.writeTo(out);
        out.flush();
        msgContent = baos.toString();
    }
    System.out.println("message: " + msgContent);
}