9 Parlay X Web Services Multimedia Messaging API

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:

1. 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.

2. SessionTimeout - Set the time in seconds after which HTTP sessions time out. Data for all timed out sessions is discarded.

3. 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).

4. 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.

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);

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());
}

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");

msgNotiMgrClient.stopMessageNotification(correlator);

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);
    }
}

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);
}