Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.7)

Part Number E10224-20
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

64 Sending and Receiving Messages using the User Messaging Service Java API

This chapter describes how to use the User Messaging Service (UMS) client API to develop applications. This API serves as a programmatic entry point for Fusion Middleware application developers to incorporate messaging features within their enterprise applications.

Because the API provides a plain old java (POJO/POJI) programming model, this eliminates the needs for application developers to package and implement various Java EE modules (such as an EJB module) in an application to access UMS features. This reduces application development time because developers can create applications to run in a Java EE container without performing any additional packaging of modules, or obtaining specialized tools to perform such packaging tasks.

Consumers of the UMS Java API are not required to use any Java EE mechanism such as environment entries or other Java EE deployment descriptor artifacts. Besides the overhead involved in maintaining Java EE descriptors, many client applications already have a configuration framework that does not rely on Java EE descriptors.

This chapter includes the following sections:

Note:

To learn more about the code samples for Oracle User Messaging Service, or to run the samples yourself, refer to the samples at:

http://www.oracle.com/technetwork/indexes/samplecode/sample-ums-1454424.html

64.1 Introduction to the UMS Java API

The UMS Java API is exposed as a POJO/POJI API. Consumers of the API can get an instance of a MessagingClient object using a factory method. The consumers do not need to deploy any EJB or other Java EE modules in their applications, but must ensure that the UMS libraries are available in an application' s runtime class path. The deployment is as a shared library, "oracle.sdp.client".

The UMS Java API consists of packages grouped as follows:

The samples with source code are available on Oracle Technology Network (OTN).

64.2 Creating a UMS Client Instance and Specifying Runtime Parameters

This section describes the requirements for creating a UMS Client. You can create a MessagingClient instance by using the code in the MessagingClientFactory class. Specifically, use the MessagingClientFactory.createMessagingClient() method to create the instance.

Client applications can specify a set of parameters at runtime when instantiating a client object. For example, you configure a MessagingClient instance by specifying parameters as a map of key-value pairs in a java.util.Map<String, Object>. Among other things, the configuration parameters serve to identify the client application, point to the UMS server, and establish security credentials. Client applications are responsible for storing and loading the configuration parameters using any available mechanism.

Table 64-1 lists some configuration parameters that may be set for the Java API. In typical use cases, most of the parameters do not need to be provided and the API implementation uses sensible default values.

Table 64-1 Configuration Parameters Specified at Runtime

Parameter Notes

APPLICATION_NAME

Optional. By default, the client is identified by its deployment name. This identifier can be overridden by specifying a value for key ApplicationInfo.APPLICATION_NAME.

APPLICATION_INSTANCE_NAME

Optional. Only required for certain clustered use cases or to take advantage of session-based routing.

SDPM_SECURITY_PRINCIPAL

Optional. By default, the client's resources are available to any application with the same application name and any security principal. This behavior can be overridden by specifying a value for key ApplicationInfo.SDPM_SECURITY_PRINCIPAL. If a security principal is specified, then all subsequent requests involving the application's resources (messages, access points, and so on.) must be made using the same security principal.

MESSAGE_LISTENER_THREADS
STATUS_LISTENER_THREADS

Optional. When listeners are used to receive messages or statuses asynchronously, the number of listener worker threads can be controlled by specifying values for the MessagingConstants.MESSAGE_LISTENER_THREADS and MessagingConstants.STATUS_LISTENER_THREADS keys.

RECEIVE_ACKNOWLEDGEMENT_MODE
LISTENER_ACKNOWLEDGEMENT_MODE

Optional. When receiving messages, you can control the reliability mode by specifying values for the MessagingConstants.RECEIVE_ACKNOWLEDGEMENT_MODE (synchronous receiving) and MessagingConstants.
LISTENER_ACKNOWLEDGEMENT_MODE (asynchronous receiving) keys.


To release resources used by the MessagingClient instance when it is no longer needed, call MessagingClientFactory.remove(client). If you do not call this method, some resources such as worker threads and JMS listeners may remain active.

Example 64-1 shows code for creating a MessagingClient instance using the programmatic approach:

Example 64-1 Programmatic Approach to Creating a MessagingClient Instance

Map<String, Object> params = new HashMap<String, Object>();
// params.put(key, value);  // if optional parameters need to be specified.
MessagingClient messagingClient = MessagingClientFactory.createMessagingClient(params); 

A MessagingClient cannot be reconfigured after it is instantiated. Instead, you must create a new instance of the MessagingClient class using the desired configuration.

64.2.1 API Reference for Class MessagingClientFactory

The API reference for class MessagingClientFactory can be accessed from the Javadoc.

64.3 Sending a Message

The client application can create a message object using the MessagingFactory class of oracle.sdp.messaging. MessagingFactory. You can use other methods in this class to create Addresses, AccessPoints, MessageFilters, and MessageQueries. See the Javadoc for more information about these methods.

The client application can then send the message. The API returns a String identifier that the client application can later use to retrieve message delivery status. The status returned is the latest known status based on UMS internal processing and delivery notifications received from external gateways.

The types of messages that can be created include plaintext messages, multipart messages that can consist of text/plain and text/html parts, and messages that include the creation of delivery channel (DeliveryType) specific payloads in a single message for recipients with different delivery types.

The section includes the following topics:

64.3.1 Creating a Message

This section describes the various types of messages that can be created.

64.3.1.1 Creating a Plaintext Message

Example 64-2 shows how to create a plaintext message using the UMS Java API.

Example 64-2 Creating a Plaintext Message Using the UMS Java API

Message message = MessagingFactory.createTextMessage("This is a Plain Text message.");

or

Message message = MessagingFactory.createMessage();
message.setContent("This is a Plain Text message.", "text/plain");

64.3.1.2 Creating a Multipart/Alternative Message (with Text/Plain and Text/HTML Parts)

Example 64-3 shows how to create a multipart or alternative message using the UMS Java API.

Example 64-3 Creating a Multipart or Alternative Message Using the UMS Java API

Message message = MessagingFactory.createMessage();
MimeMultipart mp = new MimeMultipart("alternative");
MimeBodyPart mp_partPlain = new MimeBodyPart();
mp_partPlain.setContent("This is a Plain Text part.", "text/plain");
mp.addBodyPart(mp_partPlain);
MimeBodyPart mp_partRich = new MimeBodyPart();
mp_partRich
        .setContent(
                "<html><head></head><body><b><i>This is an HTML part.</i></b></body></html>",
                "text/html");
mp.addBodyPart(mp_partRich);
message.setContent(mp, "multipart/alternative");

64.3.1.3 Creating Delivery Channel-Specific Payloads in a Single Message for Recipients with Different Delivery Types

When sending a message to a destination address, there could be multiple channels involved. Oracle UMS application developers are required to specify the correct multipart format for each channel.

Example 64-4 shows how to create delivery channel (DeliveryType) specific payloads in a single message for recipients with different delivery types.

Each top-level part of a multiple payload multipart/alternative message should contain one or more values of this header. The value of this header should be the name of a valid delivery type. Refer to the available values for DeliveryType in the enum DeliveryType.

Example 64-4 Creating Delivery Channel-specific Payloads in a Single Message for Recipients with Different Delivery Types

Message message = MessagingFactory.createMessage();
 
// create a top-level multipart/alternative MimeMultipart object.
MimeMultipart mp = new MimeMultipart("alternative");
 
// create first part for SMS payload content.
MimeBodyPart part1 = new MimeBodyPart();
part1.setContent("Text content for SMS.", "text/plain");
 
part1.setHeader(Message.HEADER_NS_PAYLOAD_PART_DELIVERY_TYPE, "SMS");
 
// add first part
mp.addBodyPart(part1);
 
// create second part for EMAIL and IM payload content.
MimeBodyPart part2 = new MimeBodyPart();
MimeMultipart part2_mp = new MimeMultipart("alternative");
MimeBodyPart part2_mp_partPlain = new MimeBodyPart();
part2_mp_partPlain.setContent("Text content for EMAIL/IM.", "text/plain");
part2_mp.addBodyPart(part2_mp_partPlain);
MimeBodyPart part2_mp_partRich = new MimeBodyPart();
part2_mp_partRich.setContent("<html><head></head><body><b><i>" + "HTML content for EMAIL/IM." +
"</i></b></body></html>", "text/html");
part2_mp.addBodyPart(part2_mp_partRich);
part2.setContent(part2_mp, "multipart/alternative");
 
part2.addHeader(Message.HEADER_NS_PAYLOAD_PART_DELIVERY_TYPE, "EMAIL");
part2.addHeader(Message.HEADER_NS_PAYLOAD_PART_DELIVERY_TYPE, "IM");
 
// add second part
mp.addBodyPart(part2);
 
// set the content of the message
message.setContent(mp, "multipart/alternative");
 
// set the MultiplePayload flag to true
message.setMultiplePayload(true);

64.3.2 API Reference for Class MessagingFactory

The API reference for class MessagingFactory can be accessed from the Javadoc.

64.3.3 API Reference for Interface Message

The API reference for interface Message can be accessed from the Javadoc.

64.3.4 API Reference for Enum DeliveryType

The API reference for enum DeliveryType can be accessed from the Javadoc.

64.3.5 Addressing a Message

This section describes type of addresses and how to create address objects.

64.3.5.1 Types of Addresses

There are two types of addresses, device addresses and user addresses. A device address can be of various types, such as email addresses, instant messaging addresses, and telephone numbers. User addresses are user IDs in a user repository.

64.3.5.2 Creating Address Objects

You can address senders and recipients of messages by using the class MessagingFactory to create Address objects defined by the Address interface.

64.3.5.2.1 Creating a Single Address Object

Example 64-5 shows code for creating a single Address object:

Example 64-5 Creating a Single Address Object

Address recipient = MessagingFactory.createAddress("Email:john@example.com");
64.3.5.2.2 Creating Multiple Address Objects in a Batch

Example 64-6 shows code for creating multiple Address objects in a batch:

Example 64-6 Creating Multiple Address Objects in a Batch

String[] recipientsStr = {"Email:john@example.com", "SMS:123456"};
Address[] recipients = MessagingFactory.createAddress(recipientsStr);
64.3.5.2.3 Adding Sender or Recipient Addresses to a Message

Example 64-7 shows code for adding sender or recipient addresses to a message:

Example 64-7 Adding Sender or Recipient Addresses to a Message

Address sender = MessagingFactory.createAddress("Email:john@example.com");
Address recipient = MessagingFactory.createAddress("Email:jane@example.com");
message.addSender(sender);
message.addRecipient(recipient);

64.3.5.3 Creating a Recipient with a Failover Address

Example 64-8 shows code for creating a recipient with a failover address:

Example 64-8 Creating a Single Address Object with Failover

String recipientWithFailoverStr = "Email:john@example.com, SMS:123456";
Address recipient = MessagingFactory.createAddress(recipientWithFailoverStr);

64.3.5.4 API Reference for Class MessagingFactory

The API reference for class MessagingFactory can be accessed from the Javadoc.

64.3.5.5 API Reference for Interface Address

The API reference for interface Address can be accessed from the Javadoc.

64.3.6 User Preference Based Messaging

When sending a message to a user recipient (to leverage the user's messaging preferences), you can pass current values for various business terms in the message as metadata. The UMS server matches the supplied facts in the message against conditions for business terms specified in the user's messaging filters.

Note:

All facts must be added as metadata in the Message.NAMESPACE_NOTIFICATION_PREFERENCES namespace. Metadata in other namespaces are ignored (for resolving user messaging preferences).

Example 64-9 shows how to specify a user recipient and supply facts for business terms for the user preferences in a message. For a complete list of supported business terms, refer to Chapter 67, "User Messaging Preferences."

Example 64-9 User Preference Based Messaging

Message message = MessagingFactory.createMessage();
// create and add a user recipient
Address userRecipient1 = MessagingFactory.createAddress("USER:sampleuser1");
message.addRecipient(userRecipient1);
// specify business term facts
message.setMetaData(Message.NAMESPACE_NOTIFICATION_PREFERENCES, "Customer
Name", "ACME");
//  where "Customer Name" is the Business Term name, and "ACME" is the
Business Term value (i.e, fact).

64.4 Retrieving Message Status

After sending a message, you can use Oracle UMS to retrieve the message status either synchronously or asynchronously.

64.4.1 Synchronous Retrieval of Message Status

To perform a synchronous retrieval of current status, use the following flow from the MessagingClient API:

String messageId = messagingClient.send(message);
Status[] statuses = messagingClient.getStatus(messageId);

or,

Status[] statuses = messagingClient.getStatus(messageId, address[]) --- where
 address[] is an array of one or more of the recipients set in the message.

64.4.2 Asynchronous Receiving of Message Status

When asynchronously receiving status, the client application specifies a Listener object and an optional correlator object. When incoming status arrives, the listener' s onStatus callback is invoked. The originally-specified correlator object is also passed to the callback method.

64.4.2.1 Creating a Listener Programmatically

Listeners are purely programmatic. You create a listener by implementing the oracle.sdp.messaging.Listener interface. You can implement it as any concrete class - one of your existing classes, a new class, or an anonymous or inner class.

The following code example shows how to implement a status listener:

import oracle.sdp.messaging.Listener;
 
    public class StatusListener implements Listener {

      @Override
      public void onMessage(Message message, Serializable correlator) {
      }  
      @Override
      public void onStatus(Status status, Serializable correlator) {
          System.out.println("Received Status: " + status + " with optional correlator: " +
 
correlator);
      }
    }

You pass a reference to the Listener object to the setStatusListener or send methods, as described in "Default Status Listener" and "Per Message Status Listener". When a status arrives for your message, the UMS infrastructure invokes the Listener's onStatus method as appropriate.

64.4.2.2 Default Status Listener

The client application typically sets a default status listener (Example 64-10). When the client application sends a message, delivery status callbacks for the message invoke the default listener's onStatus method.

Example 64-10 Default Status Listener

messagingClient.setStatusListener(new MyStatusListener());
messagingClient.send(message);

64.4.2.3 Per Message Status Listener

In this approach, the client application sends a message and specifies a Listener object and an optional correlator object (Example 64-11). When delivery status callbacks are available for that message, the specified listener's onStatus method is invoked. The originally-specified correlator object is also passed to the callback method.

Example 64-11 Per Message Status Listener

messagingClient.send(message, new MyStatusListener(), null);

64.5 Receiving a Message

This section describes how an application receives messages. To receive a message you must first register an access point. From the application perspective there are two modes for receiving a message, synchronous and asynchronous.

64.5.1 Registering an Access Point

The client application can create and register an access point, specifying that it wants to receive incoming messages sent to a particular address. Since the client application has not specified any message listeners, any received messages are held by UMS. The client application can then invoke the receive method to fetch the pending messages. When receiving messages without specifying an access point, the application receives messages for any of the access points that it has registered. Otherwise, if an access point is specified, the application receives messages sent to that access point.

AccessPoint represents one or more device addresses to receive incoming messages. An application that wants to receive incoming messages must register one or more access points that represent the recipient addresses of the messages. The server matches the recipient address of an incoming message against the set of registered access points, and routes the incoming message to the application that registered the matching access point.

You can use MessagingFactory.createAccessPoint to create an access point and MessagingClient.registerAccessPoint to register it for receiving messages.

To register an SMS access point for the number 9000:

AccessPoint accessPointSingleAddress =
 MessagingFactory.createAccessPoint(AccessPoint.AccessPointType.SINGLE_ADDRESS,
 DeliveryType.SMS, "9000");
messagingClient.registerAccessPoint(accessPointSingleAddress);

To register SMS access points in the number range 9000 to 9999:

AccessPoint accessPointRangeAddress =
 MessagingFactory.createAccessPoint(AccessPoint.AccessPointType.NUMBER_RANGE,
 DeliveryType.SMS,"9000,9999");
messagingClient.registerAccessPoint(accessPointRangeAddress);

64.5.2 Synchronous Receiving

A receive is a nonblocking operation. If there are no pending messages for the application or access point, the call returns immediately with an empty list. Receive is not guaranteed to return all available messages, but may return only a subset of available messages for efficiency reasons.

You can use the method MessagingClient.receive to synchronously receive messages. This is a convenient polling method for light-weight clients that do not want the configuration overhead associated with receiving messages asynchronously. This method returns a list of messages that are immediately available in the application inbound queue.

It performs a nonblocking call, so if no message is currently available, the method returns null.

Note:

A single invocation does not guarantee retrieval of all available messages. You must poll to ensure receiving all available messages.

64.5.3 Asynchronous Receiving

When asynchronously receiving messages, the client application registers an access point and specifies a Listener object and an optional correlator object. When incoming messages arrive at the specified access point address, the listener' s onMessage callback is invoked. The originally-specified correlator object is also passed to the callback method.

64.5.3.1 Creating a Listener Programmatically

Listeners are purely programmatic. You create a listener by implementing the oracle.sdp.messaging.Listener interface. You can implement it as any concrete class - one of your existing classes, a new class, or an anonymous or inner class.

The following code example shows how to implement a message listener:

import oracle.sdp.messaging.Listener;
 
    public class MyListener implements Listener {
 
      @Override
      public void onMessage(Message message, Serializable correlator) {
          System.out.println("Received Message: " + message + " with optional correlator: " +
correlator);
      }  
      @Override
      public void onStatus(Status status, Serializable correlator) {
          System.out.println("Received Status: " + status + " with optional correlator: " +
correlator);
      }
     
    }

You pass a reference to the Listener object to the setMessageListener or registerAccessPoint methods, as described in "Default Message Listener" and "Per Access Point Message Listener". When a message arrives for your application, the UMS infrastructure invokes the Listener's onMessage method.

64.5.3.2 Default Message Listener

The client application typically sets a default message listener (Example 64-12). This listener is invoked for any delivery statuses for messages sent by this client application that do not have an associated listener. When Oracle UMS receives messages addressed to any access points registered by this client application, it invokes the onMessage callback for the client application's default listener.

To remove a default listener, call this method with a null argument.

Example 64-12 Default Message Listener

messagingClient.setMessageListener(new MyListener());

See the sample application usermessagingsample-echo for detailed instructions on asynchronous receiving.

64.5.3.3 Per Access Point Message Listener

The client application can also register an access point and specify a Listener object and an optional correlator object (Example 64-13). When incoming messages arrive at the specified access point address, the specified listener' s onMessage method is invoked. The originally-specified correlator object is also passed to the callback method.

Example 64-13 Per Access Point Message Listener

messagingClient.registerAccessPoint(accessPoint, new MyListener(), null);

64.5.4 Message Filtering

A MessageFilter is used by an application to exercise greater control over what messages are delivered to it. A MessageFilter contains a matching criterion and an action. An application can register a series of message filters; they are applied in order against an incoming (received) message; if the criterion matches the message, the action is taken. For example, an application can use MessageFilters to implement necessary blacklists, by rejecting all messages from a given sender address.

You can use MessagingFactory.createMessageFilter to create a message filter, and MessagingClient.registerMessageFilter to register it. The filter is added to the end of the current filter chain for the application. When a message is received, it is passed through the filter chain in order; if the message matches a filter's criterion, the filter's action is taken immediately. If no filters match the message, the default action is to accept the message and deliver it to the application.For example, to reject a message with the subject "spam":

MessageFilter subjectFilter = MessagingFactory.createMessageFilter("spam",
 MessageFilter.FieldType.SUBJECT, null, MessageFilter.Action.REJECT);
messagingClient.registerMessageFilter(subjectFilter);

To reject messages from email address spammer@foo.com:

MessageFilter senderFilter =
 MessagingFactory.createBlacklistFilter("spammer@foo.com");
messagingClient.registerMessageFilter(senderFilter);

64.6 Configuring for a Cluster Environment

The API supports an environment where client applications and the UMS server are deployed in a cluster environment. For a clustered deployment to function as expected, client applications must be configured correctly. The following rules apply:

64.7 Configuring Security

Client applications may need to specify one or more additional configuration parameters (described in Table 64-1) to establish a secure listener.

64.8 Threading Model

Client applications that use the UMS Java API are usually multithreaded. Typical scenarios include a pool of EJB instances, each of which uses a MessagingClient instance; and a servlet instance that is serviced by multiple threads in a web container. The UMS Java API supports the following thread model:

The following are typical use cases:

64.8.1 Listener Threading

You can achieve asynchronous listening by spawning one or more worker threads that listen to the configured JMS queues for incoming messages and statuses. By default, one worker thread is spawned for incoming messages, and one worker thread is spawned for incoming status notifications (assuming at least one message or status listener is registered, respectively). Client applications can increase the concurrency of asynchronous processing by configuring additional worker threads. This is done by specifying integer values for the MessagingConstants.MESSAGE_LISTENER_THREADS and MessagingConstants.STATUS_LISTENER_THREADS keys, settings these values to the desired number of worker threads in the configuration parameters used when creating a MessagingClient instance.

64.9 Using the UMS Client API to Build a Client Application

This section describes how to create an application called usermessagingsample, a web client application that uses the UMS Client API for both outbound messaging and the synchronous retrieval of message status. usermessagingsample also supports inbound messaging. Once you have deployed and configured usermessagingsample, you can use it to send a message to an email client.

Note:

To learn more about the code samples for Oracle User Messaging Service, or to run the samples yourself, refer to the Oracle SOA Suite samples.

Once you have navigated to this page, you can find code samples for Oracle User Messaging Service by entering the search term "UMS" and clicking Search.

This sample focuses on a Web Application Module (WAR), which defines some HTML forms and servlets. You can examine the code and corresponding XML files for the web application module from the provided usermessagingsample-src.zip source. The servlets uses the UMS Client API to create an UMS Client instance (which in turn registers the application's information) and sends messages.

This application, which is packaged as a Enterprise ARchive file (EAR) called usermessagingsample.ear, has the following structure:

The prebuilt sample application, and the source code (usermessagingsample-src.zip) are available on OTN.

64.9.1 Overview of Development

The following steps describe the process of building an application capable of outbound messaging using usermessagingsample.ear as an example:

  1. Section 64.9.2, "Configuring the Email Driver"

  2. Section 64.9.3, "Using JDeveloper 11g to Build the Application"

  3. Section 64.9.4, "Deploying the Application"

  4. Section 64.9.5, "Testing the Application"

64.9.2 Configuring the Email Driver

To enable the Oracle User Messaging Service's email driver to perform outbound messaging and status retrieval, configure the email driver as follows:

  • Enter the name of the SMTP mail server as the value for the OutgoingMailServer property.

Note:

This sample application is generic and can support outbound messaging through other channels when the appropriate messaging drivers are deployed and configured.

64.9.3 Using JDeveloper 11g to Build the Application

This section describes using a Windows-based build of JDeveloper to build, compile, and deploy usermessagingsample through the following steps:

64.9.3.1 Opening the Project

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

    Figure 64-1 Oracle JDeveloper Open Application Window

    Description of Figure 64-1 follows
    Description of "Figure 64-1 Oracle JDeveloper Open Application Window "

    In the Oracle JDeveloper main window, the project appears.

    Figure 64-2 Oracle JDeveloper Main Window

    Description of Figure 64-2 follows
    Description of "Figure 64-2 Oracle JDeveloper Main Window "

  2. 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-web, and select Project Properties.

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

      Figure 64-3 Verifying Libraries

      Description of Figure 64-3 follows
      Description of "Figure 64-3 Verifying Libraries "

    3. Click OK.

  3. Explore the Java files under the usermessagingsample-web project to see how the messaging client APIs are used to send messages, get statuses, and synchronously receive messages. The MessagingClient instance is created in SampleUtils.java in the project.

64.9.4 Deploying the Application

Perform the following steps to deploy the application:

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

  2. Deploy the application by selecting the usermessagingsample application, Deploy, usermessagingsample, to, and SOA_server (Figure 64-4).

    Figure 64-4 Deploying the Project

    Description of Figure 64-4 follows
    Description of "Figure 64-4 Deploying the Project"

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

  4. 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 optionally configure a default device for the user receiving the message in User Messaging Preferences.

64.9.5 Testing the Application

Once usermessagingsample has been deployed to a running instance of Oracle WebLogic Server, perform the following:

  1. Launch a web browser and enter the address of the sample application as follows: http://host:http-port/usermessagingsample/. For example, enter http://localhost:7001/usermessagingsample/ into the browser's navigation bar.

    When prompted, enter login credentials. For example, username weblogic. The browser page for testing messaging samples appears (Figure 64-5).

    Figure 64-5 Testing the Sample Application

    Description of Figure 64-5 follows
    Description of "Figure 64-5 Testing the Sample Application"

  2. Click Send sample message. The Send Message page appears (Figure 64-6).

    Figure 64-6 Addressing the Test Message

    Description of Figure 64-6 follows
    Description of "Figure 64-6 Addressing the Test Message"

  3. As an optional step, enter the sender address in the following format:

    Email:sender_address.

    For example, enter Email:sender@example.com.

  4. Enter one or more recipient addresses. For example, enter Email:recipient@example.com. Enter multiple addresses as a comma-separated list as follows:

    Email:recipient_address1, Email:recipient_address2.

    If you have configured user messaging preferences, you can address the message simply to User:username. For example, User:weblogic.

  5. As an optional step, enter a subject line or content for the email.

  6. Click Send. The Message Status page appears, showing the progress of transaction (Message received by Messaging engine for processing in Figure 64-7).

    Figure 64-7 Message Status

    Description of Figure 64-7 follows
    Description of "Figure 64-7 Message Status"

  7. Click Refresh to update the status. When the email message has been delivered to the email server, the Status Content field displays Outbound message delivery to remote gateway succeeded., as illustrated in Figure 64-8.

    Figure 64-8 Checking the Message Status

    Description of Figure 64-8 follows
    Description of "Figure 64-8 Checking the Message Status"

64.10 Using the UMS Client API to Build a Client Echo Application

This section describes how to create an application called usermessagingsample-echo, a demo client application that uses the UMS Client API to asynchronously receive messages from an email address and echo a reply back to the sender.

Note:

To learn more about the code samples for Oracle User Messaging Service, or to run the samples yourself, refer to the Oracle SOA Suite samples.

Once you have navigated to this page, you can find code samples for Oracle User Messaging Service by entering the search term "UMS" and clicking Search.

This application, which is packaged as a Enterprise Archive file (EAR) called usermessagingsample-echo.ear, has the following structure:

The prebuilt sample application, and the source code (usermessagingsample-echo-src.zip) are available on OTN.

64.10.1 Overview of Development

The following steps describe the process of building an application capable of asynchronous inbound and outbound messaging using usermessagingsample-echo.ear as an example:

  1. Section 64.10.2, "Configuring the Email Driver"

  2. Section 64.10.3, "Using JDeveloper 11g to Build the Application"

  3. Section 64.10.4, "Deploying the Application"

  4. Section 64.10.5, "Testing the Application"

64.10.2 Configuring the Email Driver

To enable the Oracle User Messaging Service's email driver to perform inbound and outbound messaging and status retrieval, configure the email driver as follows:

  • Enter the name of the SMTP mail server as the value for the OutgoingMailServer property.

  • Enter the name of the IMAP4/POP3 mail server as the value for the IncomingMailServer property. Also, configure the incoming user name, and password.

Note:

This sample application is generic and can support inbound and outbound messaging through other channels when the appropriate messaging drivers are deployed and configured.

64.10.3 Using JDeveloper 11g to Build the Application

This section describes using a Windows-based build of JDeveloper to build, compile, and deploy usermessagingsample-echo through the following steps:

64.10.3.1 Opening the Project

  1. Unzip usermessagingsample-echo-src.zip, to the JDEV_HOME/communications/
    samples/ directory. This directory must be used for the shared library references to be valid in the project.

    Note:

    If you choose to use a different directory, you must update the oracle.sdp.messaging library source path to JDEV_HOME/
    communications/modules/oracle.sdp.messaging_11.1.1/
    sdpmessaging.jar.

  2. Open usermessagingsample-echo.jws (contained in the .zip file) in Oracle JDeveloper (Figure 64-9).

    Figure 64-9 Opening the Project

    Description of Figure 64-9 follows
    Description of "Figure 64-9 Opening the Project"

    In the Oracle JDeveloper main window the project appears (Figure 64-10).

    Figure 64-10 Oracle JDeveloper Main Window

    Description of Figure 64-10 follows
    Description of "Figure 64-10 Oracle JDeveloper Main Window"

  3. Verify that the build dependencies for the sample application have been satisfied by checking that the following library has been added to the usermessagingsample-echo-web module.

    • Library: oracle.sdp.messaging, Classpath: JDEV_HOME/
      communications/modules/oracle.sdp.messaging_11.1.1/
      sdpmessaging.jar. This is the Java library used by UMS and applications that use UMS to send and receive messages.

    Perform the following steps for each module:

    1. In the Application Navigator, right-click the module and select Project Properties.

    2. In the left pane, select Libraries and Classpath (Figure 64-11).

      Figure 64-11 Verifying Libraries

      Description of Figure 64-11 follows
      Description of "Figure 64-11 Verifying Libraries"

    3. Click OK.

  4. Explore the Java files under the usermessagingsample-echo-web project to see how the messaging client APIs are used to register and unregister access points, and how the EchoListener is used to asynchronously receive messages.

64.10.4 Deploying the Application

Perform the following steps to deploy the application:

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

  2. Deploy the application by selecting the usermessagingsample-echo application, Deploy, usermessagingsample-echo, to, and SOA_server (Figure 64-12).

    Figure 64-12 Deploying the Project

    Description of Figure 64-12 follows
    Description of "Figure 64-12 Deploying the Project"

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

  4. 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 optionally configure a default device for the user receiving the message in User Messaging Preferences.

64.10.5 Testing the Application

Once usermessagingsample-echo has been deployed to a running instance of Oracle WebLogic Server, perform the following:

  1. Launch a web browser and enter the address of the sample application as follows: http://host:http-port/usermessagingsample-echo/. For example, enter http://localhost:7001/usermessagingsample-echo/ into the browser's navigation bar.

    When prompted, enter login credentials. For example, username weblogic. The browser page for testing messaging samples appears (Figure 64-13).

    Figure 64-13 Testing the Sample Application

    Description of Figure 64-13 follows
    Description of "Figure 64-13 Testing the Sample Application"

  2. Click Register/Unregister Access Points. The Access Point Registration page appears (Figure 64-14).

    Figure 64-14 Registering an Access Point

    Description of Figure 64-14 follows
    Description of "Figure 64-14 Registering an Access Point"

  3. Enter the access point address in the following format:

    EMAIL:server_address.

    For example, enter EMAIL:myserver@example.com.

  4. Select the Action Register and Click Submit. The registration status page appears, showing "Registered" in Figure 64-15).

    Figure 64-15 Access Point Registration Status

    Description of Figure 64-15 follows
    Description of "Figure 64-15 Access Point Registration Status"

  5. Send a message from your messaging client (for email, your email client) to the address you just registered as an access point in the previous step.

    If the UMS messaging driver for that channel is configured correctly, you should expect to receive an echo message back from the usermessagingsample-echo application.

64.11 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-16).

    Figure 64-16 New Application Server Connection

    Description of Figure 64-16 follows
    Description of "Figure 64-16 New Application Server Connection"

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

  3. Select WebLogic 10.3 as the Connection Type.

    Figure 64-17 New Application Server Connection

    Description of Figure 64-17 follows
    Description of "Figure 64-17 New Application Server Connection"

  4. Enter the authentication information. A typical value for user name 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 WLS Domain.

  6. Click Next.

  7. In the Test dialog, click Test Connection.

  8. Verify that the message Success! appears.

    The Application Server Connection has been created.