Oracle® WebLogic Communication Services Developer's Guide 11g Release 1 (11.1.1) E13807-02 |
|
![]() Previous |
![]() Next |
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:
Section 17.5, "Using the UMS EJB Client API to Build a Client Application"
Section 17.6, "Using the UMS EJB Client API to Build a Client Echo Application"
Section 17.7, "Creating a New Application Server Connection"
The UMS Java API supports developing applications for EJB 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
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).
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.
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:
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.
This section describes the various types of messages that can be created.
Example 17-3 shows how to create a plaintext message using the UMS Java API.
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");
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);
The API reference for class MessageFactory can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.
The API reference for interface Message can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.
The API reference for enum DeliveryType can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.
This section describes type of addresses and how to create address objects.
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.
You can address senders and recipients of messages by using the class AddressFactory to create Address objects defined by the Address interface.
Example 17-6 shows code for creating a single Address object:
Example 17-7 shows code for creating multiple Address objects in a batch:
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);
Example 17-9 shows code for creating a recipient with a Failover address:
The API reference for class AddressFactory can be accessed from the Oracle Fusion Middleware User Messaging Service API Reference.
You can use Oracle UMS to retrieve message status either synchronously or asynchronously.
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.
To retrieve an asynchronous notification of message status, perform the following:
Implement a status listener.
Register a status listener (declarative way)
Send a message (messagingClient.send(message);)
The application automatically gets the status through an onStatus(status) callback of the status listener.
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.
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);
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. |
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.
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);
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:
usermessagingsample.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 EJB 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 pre-built sample application, and the source code (usermessagingsample-src.zip) are available on OTN.
The following steps describe the process of building an application capable of outbound messaging using usermessagingsample.ear as an example:
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. |
This section describes using a Windows-based build of JDeveloper to build, compile, and deploy usermessagingsample through the following steps:
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. |
Open usermessagingsample.jws (contained in the .zip file) in Oracle JDeveloper.
Figure 17-1 Oracle JDeveloper Main Window
In the Oracle JDeveloper main window the project appears.
Figure 17-2 Oracle JDeveloper Main Window
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.
In the Application Navigator, right click on web module usermessagingsample-web, and select Project Properties.
In the left pane, select Libraries and Classpath.
Click OK.
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.
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).
Perform the following steps to deploy the application:
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".
Deploy the application by selecting the usermessagingsample application, Deploy, usermessagingsample, to, and SOA_server (Figure 17-4).
Verify that the message "Build Successful" appears in the log.
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. |
Once usermessagingsample has been deployed to a running instance of WLS, perform the following:
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
Click Send sample message. The Send Message page appears (Figure 17-6).
As an optional step, enter the sender address in the following format:
Email:<sender_address>.
For example, enter Email:sender@oracle.com.
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.
As an optional step, enter a subject line or content for the e-mail.
Click Send. The Message Status page appears, showing the progress of transaction ("Message received by Messaging engine for processing," in Figure 17-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.
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:
usermessagingsample-echo.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 EJB 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 pre-built sample application, and the source code (usermessagingsample-echo-src.zip) are available on OTN.
The following steps describe the process of building an application capable of asynchronous inbound and outbound messaging using usermessagingsample-echo.ear as an example:
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. |
This section describes using a Windows-based build of JDeveloper to build, compile, and deploy usermessagingsample-echo through the following steps:
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. |
Open usermessagingsample-echo.jws (contained in the .zip file) in Oracle JDeveloper (Figure 17-9).
In the Oracle JDeveloper main window the project appears (Figure 17-10).
Figure 17-10 Oracle JDeveloper Main Window
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:
In the Application Navigator, right click on the module and select Project Properties.
In the left pane, select Libraries and Classpath (Figure 17-11).
Click OK.
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.
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).
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.
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>
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. |
Perform the following steps to deploy the application:
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."
Deploy the application by selecting the usermessagingsample-echo application, Deploy, usermessagingsample-echo, to, and SOA_server (Figure 17-12).
Verify that the message "Build Successful" appears in the log.
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. |
Once usermessagingsample-echo has been deployed to a running instance of WLS, perform the following:
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
Click Register/Unregister Access Points. The Access Point Registration page appears (Figure 17-14).
Enter the access point address in the following format:
EMAIL:<server_address>.
For example, enter EMAIL:myserver@example.com.
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
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.
Perform the following steps to create a new Application Server Connection.
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
Name the connection “SOA_server” and click Next (Figure 17-17).
Select "WebLogic 10.3" as the Connection Type.
Figure 17-17 New Application Server Connection
Enter the authentication information. The typical values are:
Username: weblogic
Password: weblogic
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.
Click Next.
On the Test screen click Test Connection.
Verify that the message “Success!” appears.
The Application Server Connection has been created.