Skip Headers
Oracle® WebLogic Communication Services Developer's Guide
11g Release 1 (11.1.1)

Part Number E13807-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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

This chapter describes how to use the User Messaging Service (UMS) API to develop applications, and describes how to build two sample applications, usermessagingsample.ear and usermessagingsample-echo.ear. It contains the following topics:

17.1 Overview of UMS Java API

The UMS Java API supports developing applications for EJB clients. It consists of packages grouped as follows:

17.1.1 Creating a J2EE Application Module

There are two choices for a J2EE application module that uses the UMS EJB Client API:

  • EJB Application Module - Stateless Session Bean - This is a backend, core message-receiving or message-sending application.

  • Web Application Module - This is for applications that have an HTML or Web frontend.

Whichever application module is selected uses the UMS Client API to register the application with the UMS Server and subsequently invoke operations to send or retrieve messages, status, and register or unregister access points. For a complete list of operations refer to the Oracle Fusion Middleware User Messaging Service API Reference.

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

17.2 Creating a UMS Client Instance

This section describes the requirements for creating a UMS EJB Client. You can create a MessagingEJBClient instance by using the code in the MessagingClientFactory class.

When creating an application using the UMS EJB Client, the application must be packaged as an EAR file, and the usermessagingclient-ejb.jar module bundled as an EJB module.

17.2.1 Creating a MessagingEJBClient Instance Using a Programmatic or Declarative Approach

Example 17-1 shows code for creating a MessagingEJBClient instance using the programmatic approach:

Example 17-1 Programmatic Approach to Creating a MessagingEJBClient Instance

ApplicationInfo appInfo = new ApplicationInfo();
appInfo.setApplicationName("SampleApp");
appInfo.setApplicationInstanceName("SampleAppInstance");
MessagingClient mClient = MessagingClientFactory.createMessagingEJBClient(appInfo);

You can also create a MessagingEJBClient instance using a declarative approach. The declarative approach is normally the preferred approach since it allows you to make changes at deployment time.

You must specify all the required Application Info properties as environment entries in your J2EE module's descriptor (ejb-jar.xml, or web.xml).

Example 17-2 shows code for creating a MessagingEJBClient instance using the declarative approach:

Example 17-2 Declarative Approach to Creating a MessagingEJBClient Instance

MessagingClient mClient = MessagingClientFactory.createMessagingEJBClient();

17.2.2 API Reference for Class MessagingClientFactory

The API reference for class MessagingClientFactory can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.

17.3 Sending a Message

You can create a message by using the code in the MessageFactory class and Message interface of oracle.sdp.messaging.

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.

17.3.1 Creating a Message

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

17.3.1.1 Creating a Plaintext Message

Example 17-3 shows how to create a plaintext message using the UMS Java API.

Example 17-3 Creating a Plaintext Message Using the UMS Java API

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

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

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

Example 17-4 Creating a Multipart or Alternative Message Using the UMS Java API

Message message = MessageFactory.getInstance().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");

17.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 17-5 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 must contain one or more values of this header. The value of this header must be the name of a valid delivery type. Refer to the available values for DeliveryType in the enum DeliveryType.

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

Message message = MessageFactory.getInstance().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);

17.3.2 API Reference for Class MessageFactory

The API reference for class MessageFactory can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.

17.3.3 API Reference for Interface Message

The API reference for interface Message can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.

17.3.4 API Reference for Enum DeliveryType

The API reference for enum DeliveryType can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.

17.3.5 Addressing a Message

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

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

17.3.5.2 Creating Address Objects

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

17.3.5.2.1 Creating a Single Address Object

Example 17-6 shows code for creating a single Address object:

Example 17-6 Creating a Single Address Object

Address recipient = AddressFactory.getInstance().createAddress("Email:john.doe@oracle.com");
17.3.5.2.2 Creating Multiple Address Objects in a Batch

Example 17-7 shows code for creating multiple Address objects in a batch:

Example 17-7 Creating Multiple Address Objects in a Batch

String[] recipientsStr = {"Email:john.doe@oracle.com", "IM:jabber|john.doe@oracle.com"};
Address[] recipients = AddressFactory.getInstance().createAddress(recipientsStr);
17.3.5.2.3 Adding Sender or Recipient Addresses to a Message

Example 17-8 shows code for adding sender or recipient addresses to a message:

Example 17-8 Adding Sender or Recipient Addresses to a Message

Address sender = AddressFactory.getInstance().createAddress("Email:john.doe@oracle.com");
Address recipient = AddressFactory.getInstance().createAddress("Email:jane.doe@oracle.com");
message.addSender(sender);
message.addRecipient(recipient);

17.3.5.3 Creating a Recipient with a Failover Address

Example 17-9 shows code for creating a recipient with a Failover address:

Example 17-9 Creating a Single Address Object with Failover

String recipientWithFailoverStr = "Email:john.doe@oracle.com, IM:jabber|john.doe@oracle.com";
Address recipient = AddressFactory.getInstance().createAddress(recipientWithFailoverStr);

17.3.5.4 API Reference for Class AddressFactory

The API reference for class AddressFactory can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.

17.3.5.5 API Reference for Interface Address

The API reference for interface Address can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.

17.3.6 Retrieving Message Status

You can use Oracle UMS to retrieve message status either synchronously or asynchronously.

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

17.3.6.2 Asynchronous Notification of Message Status

To retrieve an asynchronous notification of message status, perform the following:

  1. Implement a status listener.

  2. Register a status listener (declarative way)

  3. Send a message (messagingClient.send(message);)

  4. The application automatically gets the status through an onStatus(status) callback of the status listener.

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

17.4.1 Registering an 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 AccessPointFactory.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 =
 AccessPointFactory.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 =
 AccessPointFactory.createAccessPoint(AccessPoint.AccessPointType.NUMBER_RANGE,
 DeliveryType.SMS,"9000,9999");
messagingClient.registerAccessPoint(accessPointRangeAddress);

17.4.2 Synchronous Receiving

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 non-blocking 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.

17.4.3 Asynchronous Receiving

Asynchronous receiving involves a number of tasks, including configuring MDBs and writing a Stateless Session Bean message listener. See the sample application usermessagingsample-echo for detailed instructions.

17.4.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 get 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 desired blacklists, by rejecting all messages from a given sender address.

You can use MessageFilterFactory.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 = MessageFilterFactory.createMessageFilter("spam",
 MessageFilter.FieldType.SUBJECT, null, MessageFilter.Action.REJECT);
messagingClient.registerMessageFilter(subjectFilter);

To reject messages from e-mail address "spammer@foo.com":

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

17.5 Using the UMS EJB 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 EJB 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 e-mail client.

Of the two application modules choices described in Section 17.1.1, "Creating a J2EE Application Module", this sample focuses on the Web Application Module (WAR), which defines some HTML forms and servlets. You can examine the code and corresponding XML files for the Web App module from the provided usermessagingsample-src.zip source. The servlets uses the UMS EJB Client API to create an UMS EJB Client instance (which in turn registers the application's info) and sends messages.

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

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

17.5.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 17.5.2, "Configuring the E-Mail Driver"

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

  3. Section 17.5.4, "Deploying the Application"

  4. Section 17.5.5, "Testing the Application"

17.5.2 Configuring the E-Mail Driver

To enable the Oracle User Messaging Service's E-Mail Driver to perform outbound messaging and status retrieval, configure the E-Mail 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.

17.5.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:

17.5.3.1 Opening the Project

  1. Unzip usermessagingsample-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.jws (contained in the .zip file) in Oracle JDeveloper.

    Figure 17-1 Oracle JDeveloper Main Window

    Description of Figure 17-1 follows
    Description of "Figure 17-1 Oracle JDeveloper Main Window "

    In the Oracle JDeveloper main window the project appears.

    Figure 17-2 Oracle JDeveloper Main Window

    Description of Figure 17-2 follows
    Description of "Figure 17-2 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 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 SDP Messaging to send and receive messages.

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

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

      Figure 17-3 Verifying Libraries

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

    3. Click OK.

  4. Verify that the usermessagingclient-ejb project exists in the application. This is an EJB module that packages the messaging client beans used by SDP Messaging applications. The module allows the application to connect with the UMS server.

  5. 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 application info that is registered with the UMS Server is specified programmatically in SampleUtils.java in the project (Example 17-10).

    Example 17-10 Application Information

    ApplicationInfo appInfo = new ApplicationInfo();
          appInfo.setApplicationName(SampleConstants.APP_NAME);
          appInfo.setApplicationInstanceName(SampleConstants.APP_INSTANCE_NAME);
          appInfo.setSecurityPrincipal(request.getUserPrincipal().getName());
    

17.5.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 17.7, "Creating a New Application Server Connection".

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

    Figure 17-4 Deploying the Project

    Description of Figure 17-4 follows
    Description of "Figure 17-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.

    Note:

    Refer to "Configuring Notifications" in the Oracle Fusion Middleware SOA Developer's Guide for more information.

17.5.5 Testing the Application

Once usermessagingsample has been deployed to a running instance of WLS, 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 17-5).

    Figure 17-5 Testing the Sample Application

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

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

    Figure 17-6 Addressing the Test Message

    Description of Figure 17-6 follows
    Description of "Figure 17-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@oracle.com.

  4. Enter one or more recipient addresses. For example, enter Email:recipient@oracle.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 e-mail.

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

    Figure 17-7 Message Status

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

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

    Figure 17-8 Checking the Message Status

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

17.6 Using the UMS EJB 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 EJB Client API to asynchronously receive messages from an e-mail address and echo a reply back to the sender.

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

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

17.6.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 17.6.2, "Configuring the E-Mail Driver"

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

  3. Section 17.6.4, "Deploying the Application"

  4. Section 17.6.5, "Testing the Application"

17.6.2 Configuring the E-Mail Driver

To enable the Oracle User Messaging Service's E-Mail Driver to perform inbound and outbound messaging and status retrieval, configure the E-Mail 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.

17.6.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:

17.6.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 17-9).

    Figure 17-9 Opening the Project

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

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

    Figure 17-10 Oracle JDeveloper Main Window

    Description of Figure 17-10 follows
    Description of "Figure 17-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 and usermessagingsample-echo-ejb modules.

    • 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 SDP Messaging to send and receive messages.

    Perform the following steps for each module:

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

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

      Figure 17-11 Verifying Libraries

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

    3. Click OK.

  4. Verify that the usermessagingclient-ejb project exists in the application. This is an EJB module that packages the messaging client beans used by SDP Messaging applications. The module allows the application to connect with the UMS server.

  5. Explore the Java files under the usermessagingsample-echo-ejb project to see how the messaging client APIs are used to asynchronously receive messages (ClientReceiverBean), and send messages (ClientSenderBean).

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

  7. Note that the application info that is registered with the UMS Server is specified declaratively in the usermessagingclient-ejb project's ejb-jar.xml. (Example 17-11).

    Example 17-11 Application Information

    <env-entry>
                    <env-entry-name>sdpm/ApplicationName</env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
                    <env-entry-value>UMSEchoApp</env-entry-value>
                </env-entry>
                <env-entry>
                    <env-entry-name>sdpm/ApplicationInstanceName</env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
                    <env-entry-value>UMSEchoAppInstance</env-entry-value>
                </env-entry>
     
                <env-entry>
                   <env-entry-name>sdpm/ReceivingQueuesInfo</env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMAppDefRcvQ1</env-entry-value>
                </env-entry>
     
                <env-entry>
                   <env-entry-name>                 sdpm/MessageListenerSessionBeanJNDIName                 </env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
                    <env-entry-value>                   ejb/umsEchoApp/ClientReceiverLocal</env-entry-value>
                </env-entry>
                <env-entry>
                    <env-entry-name>                  sdpm/MessageListenerSessionBeanHomeClassName</env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
                    <env-entry-value>                  oracle.sdp.messaging.sample.ejbApp.ClientReceiverHomeLocal                  </env-entry-value>
                  </env-entry>
                  <env-entry>
                    <env-entry-name>                  sdpm/StatusListenerSessionBeanJNDIName                  </env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
                    <env-entry-value>ejb/umsEchoApp/ClientReceiverLocal</env-entry-value>
                </env-entry>
                <env-entry>
                    <env-entry-name>sdpm/StatusListenerSessionBeanHomeClassName</env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
                    <env-entry-value>oracle.sdp.messaging.sample.ejbApp.ClientReceiverHomeLocal</env-entry-value>
                </env-entry>                
    
  8. Note that the ApplicationName ("UMSEchoApp") and ApplicationInstanceName ("UMSEchoAppInstance") are also used in the Message Selector for the MessageDispatcherBean MDB, which is used for asynchronous receiving of messages and statuses placed in the application receiving queue (Example 17-12).

    Example 17-12 Application Information

    <activation-config-property>
      <activation-config-property-name>
        messageSelector
      </activation-config-property-name>
      <activation-config-property-value>
        appName='UMSEchoApp' or sessionName='UMSEchoApp-UMSEchoAppInstance'
      </activation-config-property-value>
    </activation-config-property>
                
    

    Note:

    If you chose a different ApplicationName and ApplicationInstanceName for your own application, remember to update this message selector. Asynchronous receiving does not work otherwise.

17.6.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 17.7, "Creating a New Application Server Connection."

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

    Figure 17-12 Deploying the Project

    Description of Figure 17-12 follows
    Description of "Figure 17-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.

    Note:

    Refer to "Configuring Notifications" in the Oracle Fusion Middleware SOA Developer's Guide for more information.

17.6.5 Testing the Application

Once usermessagingsample-echo has been deployed to a running instance of WLS, 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 17-13).

    Figure 17-13 Testing the Sample Application

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

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

    Figure 17-14 Registering an Access Point

    Description of Figure 17-14 follows
    Description of "Figure 17-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 17-15).

    Figure 17-15 Access Point Registration Status

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

  5. Send a message from your messaging client (for e-mail, your e-mail 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 can expect to receive an echo message back from the usermessagingsample-echo application.

17.7 Creating a New Application Server Connection

Perform the following steps to create a new Application Server Connection.

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

    Figure 17-16 New Application Server Connection

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

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

  3. Select "WebLogic 10.3" as the Connection Type.

    Figure 17-17 New Application Server Connection

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

  4. Enter the authentication information. The typical values are:

    Username: weblogicPassword: weblogic

  5. On the Connection screen, 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. On the Test screen click Test Connection.

  8. Verify that the message “Success!” appears.

    The Application Server Connection has been created.