64 Parlay X Web Services Multimedia Messaging API

64.2.1 sendMessage Operation

Table 64-1 describes message descriptions for the sendMessageRequest input in the sendMessage operation.

Table 64-2 describes sendMessageResponse output messages for the sendMessage operation.

64.2.2 getMessageDeliveryStatus Operation

The getMessageDeliveryStatus operation gets the delivery status for a previously sent message. The input "requestIdentifier" is the "result" value from a sendMessage operation. This is the same identifier that is referred to as a Message ID in other Messaging documentation.

Table 64-3 describes the getMessageDeliveryStatusRequest input messages for the getMessageDeliveryStatus operation.

Table 64-4 describes the getMessageDeliveryStatusResponse output messages for the getMessageDeliveryStatus operation.

64.3.1 getReceivedMessages Operation

This operation polls the server for any received messages. Note the following requirements:

• The registration ID parameter is a string that identifies the endpoint address for which the application wants to receive messages. See the discussion of the ReceiveMessageManager interface for more details.

• The Parlay X specification says that if the registration ID is not specified, all messages for this application should be returned. However, the WSDL says that the registration ID parameter is mandatory. Therefore our implementation treats the empty string ("") as the "not-specified" value. If you call getReceivedMessages with the empty string as your registration ID, you get all messages for this application. Therefore the empty string is not an allowed value of registration ID when calling startReceiveMessages.

• According to the Parlay X specification, if the received message content is "pure ASCII text", then the message content is returned inline within the MessageReference object, and the messageIdentifier (Message ID) element is null. Our implementation treats any content with Content-Type "text/plain", and with encoding "us-ascii" as "pure ASCII text" for the purposes of this operation. As per the MIME specification, if no encoding is specified, "us-ascii" is assumed, and if no Content-Type is specified, "text/plain" is assumed.

• The priority parameter is currently ignored.

Table 64-5 describes the getReceivedMessagesRequest input messages for the getReceivedMessages operation.

Table 64-6 describes the getReceivedMessagesResponse output messages for the getReceivedMessages operation.

64.3.2 getMessage Operation

The getMessage operation retrieves message content, using a message ID from a previous invocation of getReceivedMessages. There is no SOAP body in the response message; the content is returned as a single SOAP attachment.

Table 64-7 describes the getMessageRequest input messages for the getMessage operation.

There are no getMessageResponse output messages for the getMessage operation.

64.3.3 getMessageURIs Operation

The getMessageURIs retrieves message content as a list of URIs. Note the following requirements:

• These URIs are HTTP URLs that can be dereferenced to retrieve the content.

• If the inbound message has a Content-Type of "multipart", then there are multiple URIs returned, one per subpart. If the Content-Type is not "multipart", then a single URI are returned.

• Per the Parlay X specification, if the inbound messages a body text part, defined as "the message body if it is encoded as ASCII text", it is returned inline within the MessageURI object. For the purposes of our implementation, you define this behavior as follows:

  • If the message's Content-Type is "text/*" (any text type), and if the charset parameter is "us-ascii", then the content is returned inline in the MessageURI object. There are no URIs returned since there is no content other than what is returned inline.

  • If the message's Content-Type is "multipart/" (any multipart type), and if the first body part's Content-Type is "text/" with charset "us-ascii", then that part is returned inline in the MessageURI object, and there are no URIs returned corresponding to that part.

  • Per the MIME specification, if the charset parameter is omitted, the default value of "us-ascii" is assumed. If the Content-Type header is not specified for the message, then a Content-Type of "text/plain" is assumed.

Table 64-8 describes the getMessageURIsRequest input messages for the getMessageURIs operation.

Table 64-9 describes the getMessageURIsResponse output messages for the getMessageURIs operation.

64.4.1 ReceiveMessageManager Interface

ReceiveMessageManager is the Oracle-specific interface for managing client registrations for receiving messages. Clients use this interface to start and stop receiving messages at a particular address. (This is analogous to the concept of registering/unregistering access points in the Messaging API).

64.6.1 Overview

This sample demonstrates how to create a web-based chat application to send and receive messages through email, SMS, or IM. The sample uses standards-based Parlay X Web Service APIs to interact with a User Messaging server. The sample application includes web service proxy code for each of three web service interfaces: the SendMessage and ReceiveMessage services defined by Parlay X, and the ReceiveMessageManager service which is an Oracle extension to Parlay X. You define an application server connection in Oracle JDeveloper, and deploy and run the application.The application is provided as a pre-built Oracle JDeveloper project that includes a simple web chat interface.

64.6.2 Running the Pre-Built Sample

Perform the following steps to run and deploy the pre-built sample application:

1. Open the usermessagingsample-parlayx.jws (contained in the .zip file) in Oracle JDeveloper.

   In the Oracle JDeveloper main window the project appears.

   Figure 64-1 Oracle JDeveloper Main Window

   
   Description of "Figure 64-1 Oracle JDeveloper Main Window"
   
   

2. In Oracle JDeveloper, select File > Open..., then navigate to the directory above and open workspace file "usermessagingsample-parlayx.jws".

   This opens the precreated JDeveloper application for the Parlay X sample application. The application contains one web module. All of the source code for the application is in place. You must configure the parameters that are specific to your installation.

3. Satisfy the build dependencies for the sample application by ensuring the "Oracle UMS Client" library is used by the web module.

   1. In the Application Navigator, right-click web module usermessagingsample-parlayx-war, and select Project Properties.

   2. In the left pane, select Libraries and Classpath.

      Figure 64-2 Adding a Library

      
      Description of "Figure 64-2 Adding a Library"
      
      

   3. Click OK.

4. Create an Application Server Connection by right-clicking the project in the navigation pane and selecting New. Follow the instructions in Section 64.6.4, "Creating a New Application Server Connection".

5. Deploy the project by selecting the usermessasgingsample-parlayx project, Deploy, usermessasgingsample-parlayx, to, and SOA_server (Figure 64-3).

   Figure 64-3 Deploying the Project

   
   Description of "Figure 64-3 Deploying the Project"
   
   

6. Verify that the message Build Successful appears in the log.

7. Enter the default revision and click OK.

8. Verify that the message Deployment Finished appears in the deployment log.

   You have successfully deployed the application.

   Before you can run the sample you must configure any additional drivers in Oracle User Messaging Service and configure a default device for the user receiving the message in User Messaging Preferences, as described in the following sections.

   Note:

   Refer to Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for more information.

64.6.3 Testing the Sample

Perform the following steps to run and test the sample:

1. Open a web browser.

2. Navigate to the URL of the application as follows, and log in:

   http://host:port/usermessagingsample-parlayx/

   The Messaging Parlay X Sample web page appears (Figure 64-4). This page contains navigation tabs and instructions for the application.

   Figure 64-4 Messaging Parlay X Sample Web Page

   
   Description of "Figure 64-4 Messaging Parlay X Sample Web Page"
   
   

3. Click Configure and enter the following values (Figure 64-5):

   • Specify the Send endpoint. For example, http://localhost:port/sdpmessaging/parlayx/SendMessageService

   • Specify the Receive endpoint. For example, http://localhost:port/sdpmessaging/parlayx/ReceiveMessageService

   • Specify the Receive Manager endpoint. For example, http://localhost:port/sdpmessaging/parlayx/ReceiveMessageMessageService

   • Specify the Username and Password.

   • Specify a Policy (required if the User Messaging Service instance has WS security enabled).

   • Figure 64-5 Configuring the Web Service Endpoints and Credentials

     
     Description of "Figure 64-5 Configuring the Web Service Endpoints and Credentials"
     
     

4. Click Save.

5. Click Manage.

6. Enter a Registration ID to specify the registration and address at which to receive messages (Figure 64-6). You can also use this page to stop receiving messages at an address.

   Figure 64-6 Specifying a Registration ID

   
   Description of "Figure 64-6 Specifying a Registration ID"
   
   

7. Click Start.

   Verify that the message Registration operation succeeded appears.

8. Click Chat (Figure 64-7).

9. Enter recipients in the To: field in the format illustrated in Figure 64-7.

10. Enter a message.

11. Click Send.

12. Verify that the message is received.

13. Figure 64-7 Running the Sample

    
    Description of "Figure 64-7 Running the Sample"
    
    

64.6.4 Creating a New Application Server Connection

Perform the following steps to create an Application Server Connection.

1. Create a new Application Server Connection by right-clicking the project and selecting New, Connections, and Application Server Connection (Figure 64-8).

   Figure 64-8 New Application Server Connection

   
   Description of "Figure 64-8 New Application Server Connection"
   
   

2. Name the connection SOA_server and click Next (Figure 64-9).

3. Select WebLogic 10.3 as the Connection Type.

   Figure 64-9 New Application Server Connection

   
   Description of "Figure 64-9 New Application Server Connection"
   
   

4. Enter the authentication information. The typical value for username is weblogic.

5. In the Connection dialog, enter the hostname, port and SSL port for the SOA admin server, and enter the name of the domain for the Oracle WebLogic Server Domain.

6. Click Next.

7. On the Test dialog, click Test Connection.

8. Verify that the message Success! appears.

   The Application Server Connection has been created.