63 Sending and Receiving Messages using the User Messaging Service EJB API

This chapter describes how to use the User Messaging Service (UMS) EJB API to develop applications, and describes how to build two sample applications, usermessagingsample-ejb.ear and usermessagingsample-echo-ejb.ear.

Note:

The User Messaging Service EJB API (described in this chapter) is deprecated. Use the User Messaging Service Java API instead, as described in Chapter 64, "Sending and Receiving Messages using the User Messaging Service Java API".

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, see the samples at:

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

63.1 Introduction to the UMS Java API

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

  • Common and Client Packages

    • oracle.sdp.messaging

    • oracle.sdp.messaging.filter: A MessageFilter is used by an application to exercise greater control over what messages are delivered to it.

  • User Preferences Packages

    • oracle.sdp.messaging.userprefs

    • oracle.sdp.messaging.userprefs.tools

63.1.1 Creating a Java EE Application Module

There are two choices for a Java EE application module that uses the UMS Enterprise JavaBeans Client API:

  • Enterprise JavaBeans Application Module - Stateless Session Bean - This is a back end, core message-receiving or message-sending application.

  • Web Application Module - This is for applications that have an HTML or web front end.

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 UMS Javadoc.

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

63.2 Creating a UMS Client Instance

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

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

63.2.1 Creating a MessagingEJBClient Instance Using a Programmatic or Declarative Approach

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

Example 63-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 enables you to make changes at deployment time.

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

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

Example 63-2 Declarative Approach to Creating a MessagingEJBClient Instance

MessagingClient mClient = MessagingClientFactory.createMessagingEJBClient();

63.2.2 API Reference for Class MessagingClientFactory

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

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

63.3.1 Creating a Message

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

63.3.1.1 Creating a Plaintext Message

Example 63-3 shows how to create a plain text message using the UMS Java API.

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

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

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

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

63.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 can be multiple channels involved. Oracle UMS application developers are required to specify the correct multipart format for each channel.

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

63.3.2 API Reference for Class MessageFactory

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

63.3.3 API Reference for Interface Message

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

63.3.4 API Reference for Enum DeliveryType

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

63.3.5 Addressing a Message

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

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

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

63.3.5.2.1 Creating a Single Address Object

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

Example 63-6 Creating a Single Address Object

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

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

Example 63-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);
63.3.5.2.3 Adding Sender or Recipient Addresses to a Message

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

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

63.3.5.3 Creating a Recipient with a Failover Address

Example 63-9 shows code for creating a recipient with a failover address:

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

63.3.5.4 API Reference for Class AddressFactory

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

63.3.5.5 API Reference for Interface Address

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

63.3.6 Retrieving Message Status

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

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

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

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

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

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

63.4.3 Asynchronous Receiving

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

63.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 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 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 email address spammer@foo.com:

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

63.5 Using the UMS Enterprise JavaBeans 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 Enterprise JavaBeans 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, see 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.

Of the two application modules choices described in Section 63.1.1, "Creating a Java EE 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 application module from the provided usermessagingsample-src.zip source. The servlets uses the UMS Enterprise JavaBeans Client API to create an UMS Enterprise JavaBeans Client instance (which in turn registers the application's info) and sends messages.

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

  • usermessagingsample-ejb.ear

    • META-INF

      • application.xml -- Descriptor file for all of the application modules.

      • weblogic-application.xml -- Descriptor file that contains the import of the oracle.sdp.messaging shared library.

    • usermessagingclient-ejb.jar -- Contains the Message Enterprise JavaBeans Client deployment descriptors.

      • META-INF

      • ejb-jar.xml

      • weblogic-ejb-jar.xml

    • usermessagingsample-web.ear -- Contains the web-based front-end and servlets.

      • WEB-INF

      • web.xml

      • weblogic.xml

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

63.5.1 Overview of Development

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

  1. Section 63.5.2, "Configuring the Email Driver"

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

  3. Section 63.5.4, "Deploying the Application"

  4. Section 63.5.5, "Testing the Application"

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

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

63.5.3.1 Opening the Project

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

    Figure 63-1 Oracle JDeveloper Main Window

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

    In the Oracle JDeveloper main window, the project appears.

  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 63-2 Verifying Libraries

      Description of Figure 63-2 follows
      Description of "Figure 63-2 Verifying Libraries "

    3. Click OK.

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

  4. 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 63-10).

    Example 63-10 Application Information

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

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

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

    Figure 63-3 Deploying the Project

    Description of Figure 63-3 follows
    Description of "Figure 63-3 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.

63.5.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 63-4).

    Figure 63-4 Testing the Sample Application

    Description of Figure 63-4 follows
    Description of "Figure 63-4 Testing the Sample Application"

  2. Click Send sample message. The Send Message page appears (Figure 63-5).

    Figure 63-5 Addressing the Test Message

    Description of Figure 63-5 follows
    Description of "Figure 63-5 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 email.

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

    Figure 63-6 Message Status

    Description of Figure 63-6 follows
    Description of "Figure 63-6 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.

63.6 Using the UMS Enterprise JavaBeans 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 Enterprise JavaBeans 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, see 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-ejb.ear, has the following structure:

  • usermessagingsample-echo-ejb.ear

    • META-INF

      • application.xml -- Descriptor file for all of the application modules.

      • weblogic-application.xml -- Descriptor file that contains the import of the oracle.sdp.messaging shared library.

    • usermessagingclient-ejb.jar -- Contains the Message Enterprise JavaBeans Client deployment descriptors.

      • META-INF

      • ejb-jar.xml

      • weblogic-ejb-jar.xml

    • usermessagingsample-echo-ejb.jar -- Contains the application session beans (ClientSenderBean, ClientReceiverBean) that process a received message and return an echo response.

      • META-INF

      • ejb-jar.xml

      • weblogic-ejb-jar.xml

    • usermessagingsample-echo-web.war -- Contains the web-based front-end and servlets.

      • WEB-INF

      • web.xml

      • weblogic.xml

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

63.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-ejb.ear as an example:

  1. Section 63.6.2, "Configuring the Email Driver"

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

  3. Section 63.6.4, "Deploying the Application"

  4. Section 63.6.5, "Testing the Application"

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

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

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

    In the Oracle JDeveloper main window, the project appears (Figure 63-7).

    Figure 63-7 Oracle JDeveloper Main Window

    Description of Figure 63-7 follows
    Description of "Figure 63-7 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 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 63-8).

      Figure 63-8 Verifying Libraries

      Description of Figure 63-8 follows
      Description of "Figure 63-8 Verifying Libraries"

    3. Click OK.

  4. Verify that the usermessagingclient-ejb project exists in the application. This is an Enterprise JavaBeans module that packages the messaging client beans used by UMS 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 file. (Example 63-11).

    Example 63-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-e
    ntry-value>
                </env-entry>
    
  8. Note that the Application Name (UMSEchoApp) and Application Instance Name (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 63-12).

    Example 63-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 Application Name and Application Instance Name for your own application, remember to update this message selector. Asynchronous receiving does not work, otherwise.

63.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 63.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 63-9).

    Figure 63-9 Deploying the Project

    Description of Figure 63-9 follows
    Description of "Figure 63-9 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.

63.6.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 63-10).

    Figure 63-10 Testing the Sample Application

    Description of Figure 63-10 follows
    Description of "Figure 63-10 Testing the Sample Application"

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

    Figure 63-11 Registering an Access Point

    Description of Figure 63-11 follows
    Description of "Figure 63-11 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 63-12).

    Figure 63-12 Access Point Registration Status

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

63.7 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 63-13).

    Figure 63-13 New Application Server Connection

    Description of Figure 63-13 follows
    Description of "Figure 63-13 New Application Server Connection"

  2. Name the connection SOA_server and click Next (Figure 63-14).

  3. Select WebLogic 10.3 as the Connection Type.

    Figure 63-14 New Application Server Connection

    Description of Figure 63-14 follows
    Description of "Figure 63-14 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.