This chapter describes how to use the User Messaging Service (UMS) Web Service API to develop applications. This API serves as a programmatic entry point for Fusion Middleware application developers to implement UMS messaging applications that run in a remote container relative to the UMS server.
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
The UMS Web Service API is functionally identical to the Java API. The JAX-WS and JAXB bindings of the web service types and interfaces have similar names as the corresponding Java API classes. That means, the client code looks the same for both the UMS Java API and UMS Web Service API. However, the API classes are in their own package spaces and the classes from these two APIs are not interoperable.
The UMS Web Service API consists of packages grouped as follows:
Common and Client Packages
oracle.ucs.messaging.ws
oracle.ucs.messaging.ws.types
Web Service API Web Service Definition Language (WSDL) files:
messaging.wsdl: defines the operations invoked by a web service client.
listener.wsdl: defines the callback operations that a client must implement to receive asynchronous message or status notifications.
The samples with source code are available on Oracle Technology Network (OTN).
The MessagingClient object is the fundamental UMS API object that you must create in the Client application using the UMS Web Service API. You can create a instance of oracle.ucs.messaging.ws.MessagingClient by using the public constructor. Client applications can specify a set of parameters at runtime when instantiating a client object. For example, you configure a MessagingClient instance by specifying parameters as a map of key-value pairs in a java.util.Map<String, Object>. Among other things, the configuration parameters serve to identify the web service endpoint URL identifying the UMS server to communicate with, and other web service-related information such as security policies. Client applications are responsible for storing and loading the configuration parameters using any available mechanism.
You are responsible for mapping the parameters to or from whatever configuration storage mechanism is appropriate for your deployment. The MessagingClient class uses the specified key/value pairs for configuration, and passes through all parameters to the underlying JAX-WS service. Any parameters recognized by JAX-WS are valid. Table 3-1 lists the most common configuration parameters:
Table 3-1 Configuration Parameters Specified at Runtime
| Key | Type | Use |
|---|---|---|
|
|
String |
Endpoint URL for the remote UMS WS. This is typically "http://<host>:<port>/ucs/messaging/webservice". |
|
|
String |
Username to be asserted in WS-Security headers when relevant |
|
|
String[] |
Array of OWSM WS-Security policies to attach to the client's requests. These must match the policies specified on the server side. |
|
|
String |
Used for OWSM policy attachment. Specifies an alternate alias to use for looking up encryption and signing keys from the credential store. |
|
|
String |
Used for OWSM policy attachment. Specifies a credential store key to use for looking up remote username/password information from the Oracle Web Services Management credential store map. |
To know more about the OWSM policy parameters, see Java API Reference for Oracle Web Services Manager.
A MessagingClient cannot be reconfigured after it is instantiated. Instead, a new instance of the MessagingClient class must be created using the new configuration.
Example 3-1 shows code for creating a MessagingClient instance using username/token security.
Example 3-1 Creating a MessagingClient Instance, Username/Token Security
HashMap<String, Object> config = new HashMap<String, Object>();
config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
"http://example.com:8001/ucs/messaging/webservice");
config.put(ClientConstants.POLICIES, new String[] {"oracle/wss11_username_token_
with_message_protection_client_policy"});
config.put(BindingProvider.USERNAME_PROPERTY, "user1");
config.put(oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_
LOCATION, oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_LOC_
SUBJECT);
config.put(oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_CSF_KEY,
"user1-passkey");
config.put(MessagingConstants.APPLICATION_NAME, "MyUMSWSApp");
mClient = new MessagingClient(config);
Example 3-2 shows code for creating a MessagingClient instance using SAML token security.
Example 3-2 Creating a MessagingClient Instance, SAML Token Security
HashMap<String, Object> config = new HashMap<String, Object>();
config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
"http://example.com:8001/ucs/messaging/webservice");
config.put(ClientConstants.POLICIES, new String[] {"oracle/wss11_saml_token_
identity_switch_with_message_protection_client_policy"});
config.put(BindingProvider.USERNAME_PROPERTY, "user1");
config.put(oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_
LOCATION, oracle.wsm.security.util.SecurityConstants.Config.CLIENT_CREDS_LOC_
SUBJECT);
config.put(oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_
ALIAS_PROPERTY, "example.com");
config.put(MessagingConstants.APPLICATION_NAME, "MyUMSWSApp");
mClient = new MessagingClient(config);
A MessagingClient cannot be reconfigured after it is instantiated. Instead, you must create a new instance of the MessagingClient class using the desired configuration.
Factory methods are provided for creating Web Service API types in the class "oracle.ucs.messaging.ws.MessagingFactory".
Invoking the send method of MessagingClient object sends the message in a Web Service request to the UMS Server, where it is processed accordingly. The send method returns a String message identifier that the client application can later use to retrieve message delivery status, or to correlate with asynchronous status notifications that are delivered to a Listener. The status returned is the latest known status based on UMS internal processing and delivery notifications received from external gateways.
The types of messages that can be created include plaintext messages, multipart messages that can consist of text/plain and text/html parts, and messages that include the creation of delivery channel (DeliveryType) specific payloads in a single message for recipients with different delivery types.
This section describes the various types of messages that can be created.
Example 3-3 shows two ways to create a plaintext message using the UMS Web Service API.
Example 3-3 Creating a Plaintext Message Using the UMS Web Service API
Message message = MessagingFactory.createTextMessage("This is a Plain Text
message.");
or
Message message = MessagingFactory.createMessage();
message.setContent(new DataHandler(new StringDataSource("This is a Plain Text
message.", "text/plain; charset=UTF-8")));
Example 3-4 shows how to create a multipart/mixed message using the UMS Web Service API.
Example 3-4 Creating a Multipart/Mixed Message Using the UMS Web Service API
Message message = MessagingFactory.createMessage();
MimeMultipart mp = new MimeMultipart("mixed");
// Create the first body part
MimeBodyPart mp_partPlain = new MimeBodyPart();
StringDataSource plainDS = new StringDataSource("This is a Plain Text part.",
"text/plain; charset=UTF-8");
mp_partPlain.setDataHandler(new DataHandler(plainDS));
mp.addBodyPart(mp_partPlain);
byte[] imageData;
// Create or load image data in the above byte array (code not shown for brevity)
// Create the second body part
MimeBodyPart mp_partBinary = new MimeBodyPart();
ByteArrayDataSource binaryDS = new ByteArrayDataSource(imageData, "image/gif");
mp_partBinary.setDataHandler(binaryDS);
mp.addBodyPart(mp_partBinary);
message.setContent(new DataHandler(mp, mp.getContentType()));
Example 3-5 shows how to create a multipart/alternative message using the UMS Web Service API.
Example 3-5 Creating a Multipart/Alternative Message Using the UMS Web Service API
Message message = MessagingFactory.createMessage();
MimeMultipart mp = new MimeMultipart("alternative");
MimeBodyPart mp_partPlain = new MimeBodyPart();
StringDataSource plainDS = new StringDataSource("This is a Plain Text part.", "text/plain; charset=UTF-8");
mp_partPlain.setDataHandler(new DataHandler(plainDS));
mp.addBodyPart(mp_partPlain);
MimeBodyPart mp_partRich = new MimeBodyPart();
StringDataSource richDS = new StringDataSource(
"<html><head></head><body><b><i>This is an HTML part.</i></b></body></html>",
"text/html");
mp_partRich.setDataHandler(new DataHandler(richDS));
mp.addBodyPart(mp_partRich);
message.setContent(new DataHandler(mp, mp.getContentType()));
When sending a message to multiple recipients, there could be multiple channels involved. Oracle UMS application developers are required to specify the correct multipart format for each channel.
Example 3-6 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 3-6 Creating Delivery Channel-specific Payloads in a Single Message for Recipients with Different Delivery Types
Message message = MessagingFactory.createMessage();
// create a top-level multipart/alternative MimeMultipart object.
MimeMultipart mp = new MimeMultipart("alternative");
// create first part for SMS payload content.
MimeBodyPart part1 = new MimeBodyPart();
part1.setDataHandler(new DataHandler(new StringDataSource("Text content for SMS.",
"text/plain; charset=UTF-8")));
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.setDataHandler(new DataHandler(new StringDataSource("Text
content for EMAIL/IM.", "text/plain; charset=UTF-8")));
part2_mp.addBodyPart(part2_mp_partPlain);
MimeBodyPart part2_mp_partRich = new MimeBodyPart();
part2_mp_partRich.setDataHandler(new DataHandler(new
StringDataSource("<html><head></head><body><b><i>" + "HTML content for EMAIL/IM."
+
"</i></b></body></html>", "text/html; charset=UTF-8")));
part2_mp.addBodyPart(part2_mp_partRich);
part2.setContent(part2_mp, part2_mp.getContentType());
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(new DataHandler(mp, mp.getContentType()));
// set the MultiplePayload flag to true
MimeHeader multiHeader = new MimeHeader();
multiHeader.setName(oracle.sdp.client.Message.HEADER_SDPM_MULTIPLE_PAYLOAD);
multiHeader.setValue(Boolean.TRUE.toString());
message.getHeaders().add(multiHeader);
The API reference for interface Message can be accessed from the Javadoc.
The API reference for enum DeliveryType can be accessed from the User Messaging Service Java API Reference.
For information about the types of addresses and to understand how to create Address objects and to define failover address, see Section 2.3.2, "Creating an Address".
See User Messaging Service Java API Reference to know more about the Address interface.
The WS API provides support for sending and receiving messages with To/Cc/Bcc recipients for use with the email driver:
To send a message and specify a Cc/Bcc recipient, create the oracle.ucs.messaging.ws.Address object using oracle.ucs.messaging.ws.MessagingFactory.buildAddress method. The arguments are the address value (for example, user@domain.com), delivery type (for example, DeliveryType.EMAIL), and email mode (for example, "Cc" or "Bcc").
To determine the recipient type of an existing address object, for example in a received message, use the oracle.ucs.messaging.ws.MessagingFactory.getRecipientType method, passing it the Address object. It returns a string indicating the recipient type.
See User Messaging Service Java API Reference for information about the class MessagingFactory.
When you create a message using WS API, you can also supply facts for business terms for the user preferences in that message. See Section 2.3.3, "User Preference Based Messaging" for more details.
After sending a message, you can use Oracle UMS to retrieve the 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); List<Status> statuses = messagingClient.getStatus(messageId, null)
or,
List<Status> statuses = messagingClient.getStatus(messageId, addresses) --- where addresses is a "List<Address>" of one or more of the recipients set in the message.
To receive statuses asynchronously, a client application must implement the listener web service as described in listener.wsdl. There is no constraint on how the listener endpoint must be implemented. For example, one method is to use the javax.xml.ws.Endpoint JAX-WS Service API to publish a web service endpoint. This mechanism is available in Java SE 6 and does not require the consumer to explicitly define a Java EE servlet module.
However, a servlet-based listener implementation is acceptable as well.
When sending a message, the client application can provide a reference to the listener endpoint, consisting of the endpoint URL and a SOAP interface name. As statuses are generated during the processing of the message, the UMS server invokes the listener endpoint' s onStatus method to notify the client application.
You create a listener by implementing the oracle.ucs.messaging.ws.Listener interface. You can implement it as any concrete class - one of your existing classes, a new class, or an anonymous or inner class.
The following code example shows how to implement a status listener:
@PortableWebService(serviceName="ListenerService",
targetNamespace="http://xmlns.oracle.com/ucs/messaging/",
endpointInterface="oracle.ucs.messaging.ws.Listener",
wsdlLocation="META-INF/wsdl/listener.wsdl",
portName="Listener")
public class MyListener implements Listener {
public MyListener() {
}
@Override
public void onMessage(Message message, byte[] correlator) throws MessagingException {
System.out.println("I got a message!");
} @Override
public void onStatus(Status status, byte[] correlator) throws MessagingException {
System.out.println("I got a status!");
}
}
To publish the callback service, you can either declare a servlet in web.xml in a web module within your application, or use the JAX-WS javax.xml.ws.Endpoint class's publish method to programmatically publish a WS endpoint (Example 3-7):
To stop a dynamically published endpoint, call the stop() method on the Endpoint object returned from Endpoint.publish() (Example 3-8).
Once the listener web service is published, you must register the fact that your client has such an endpoint. There are the following relevant methods in the MessagingClient API:
setStatusListener(ListenerReference listener)
send(Message message, ListenerReference listener, byte[] correlator)
setStatusListener() registers a "default" status listener whose callback is invoked for any incoming status messages. A listener passed to send() is only invoked for status updates related to the corresponding message.
This section describes how an application receives 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. From the application perspective there are two modes for receiving a message, synchronous and asynchronous.
AccessPoint represents one or more device addresses for receiving incoming messages. For more details about access points, see Section 2.5.1, "Registering an Access Point".
Use the method MessagingClient.receive to synchronously receive messages that UMS makes available to the application. This is a convenient polling method for light-weight clients that do not want the configuration overhead associated with receiving messages asynchronously.
Note:
In a multi UMS server deployment, the WS API user must make sure ”receive” is called on all UMS servers. This could be done by for instance making sure the Load Balancer uses a round-robin algorithm. Or, simply do not use receive in this use-case, use asynchronous receiving using a Listener as describe in Section 3.5.3, "Asynchronous Receiving" instead.Receive is a nonblocking operation. If there are no pending messages for the application or access point, the call returns immediately with an empty list. Receive is not guaranteed to return all available messages, but may return only a subset of available messages for efficiency reasons.
Note:
A single invocation does not guarantee retrieval of all available messages. You must poll to ensure receiving all available messages.To receive messages asynchronously, a client application must implement the Listener web service as described in listener.wsdl. There is no constraint on how the listener endpoint must be implemented. For example, one mechanism is using the javax.xml.ws.Endpoint JAX-WS Service API to publish a web service endpoint. This mechanism is available in Java SE 6 and does not require the consumer to explicitly define a Java EE servlet module. However, a servlet-based listener implementation is also acceptable.
You create a listener by implementing the oracle.ucs.messaging.ws.Listener interface. You can implement it as any concrete class - one of your existing classes, a new class, or an anonymous or inner class.
The following code example shows how to implement a message listener:
@PortableWebService(serviceName="ListenerService",
targetNamespace="http://xmlns.oracle.com/ucs/messaging/",
endpointInterface="oracle.ucs.messaging.ws.Listener",
wsdlLocation="META-INF/wsdl/listener.wsdl",
portName="Listener")
public class MyListener implements Listener {
public MyListener() {
}
@Override
public void onMessage(Message message, byte[] correlator) throws MessagingException {
System.out.println("I got a message!");
} @Override
public void onStatus(Status status, byte[] correlator) throws MessagingException {
System.out.println("I got a status!");
}
}
You pass a reference to the Listener object to the setMessageListener or registerAccessPoint methods, as described in "Default Message Listener" and "Per Access Point Message Listener". When a message arrives for your application, the UMS infrastructure invokes the Listener's onMessage method.
The client application typically sets a default message listener (Example 3-9). When Oracle UMS receives messages addressed to any access points registered by this client application, it invokes the onMessage callback for the client application's default listener.
To remove a default listener, call this method with a null argument.
The client application can also register an access point and specify a Listener object and an optional correlator object (Example 3-10). When incoming messages arrive at the specified access point address, the specified listener' s onMessage method is invoked. The originally-specified correlator object is also passed to the callback method.
Example 3-10 Per Access Point Message Listener
AccessPoint accessPoint =
MessagingFactory.createAccessPoint(AccessPointType.SINGLE_ADDRESS,
DeliveryType.EMAIL, "test@example.org");
ListenerReference listenerRef = new ListenerReference();
listenerRef.setEndpoint("url_to_your_webservice_message_listener");
byte[] correlator = null; // Not to correlate the callback
messagingClient.registerAccessPoint(accessPoint, listenerRef, correlator);
A MessageFilter is used by an application to exercise greater control over what messages are delivered to it. For more details about creating message filters, see Section 2.5.4, "Message Filtering".
The UMS Web Services API supports an environment where client applications and the UMS server are deployed in a cluster environment. For a clustered deployment to function as expected, client applications must be configured correctly as explained in Section 2.6, "Configuring for a Cluster Environment".
When a message send attempt is classified as a complete failure, that is, the failover chain is exhausted, the message is automatically scheduled for resend by the UMS Server. This is repeated until the message is successfully sent or the configured number of resends is reached. However, using the UMS Web Services API it is possible to override the number of resends on a per message basis by calling the setMaxResend method as illustrated in the following example:
MessageInfo msgInfo = new oracle.ucs.messages.ws.types.MessageInfo(); msgInfo.setMaxResend(new Integer(1)); // When MessageInfo is created we must also set priority msgInfo.setPriority(PriorityType.NORMAL); message.setMessageInfo(msgInfo); String mid = client.send(message, null, null);
The status of the failover addresses can be received by calling getTotalFailovers() and getFailoverOrder(). When failover order equals total failovers, the API user knows that the failover chain is exhausted. However, the resend functionality works as a loop over the failover chain. You can call getMaxResend() and getCurrentResend() to know when the resend and failover chain is completely exhausted.
For more information about setMaxResend, getTotalFailovers() and getFailoverOrder() methods, see User Messaging Service Java API Reference.
The following sections discuss security considerations:
There are two supported security modes for the UMS Web Service: Security Assertions Markup Language (SAML) tokens and username tokens.
The supported SAML-based policy is "oracle/wss11_saml_token_with_message_protection_client_policy". This policy establishes a trust relationship between the client application and the UMS server based on the exchange of cryptographic keys. The client application is then allowed to assert a user identity that is respected by the UMS server. To use SAML tokens for WS-Security, some keystore configuration is required for both the client and the server.
See Example 3-2 for more details about configuring SAML security in a UMS web service client.
The supported username token policy is "oracle/wss11_username_token_with_message_protection_client_policy". This policy passes an encrypted username/password token in the WS-Security headers, and the server authenticates the supplied credentials. It is highly recommended that the username and password be stored in the Credential Store, in which case only a Credential Store key must be passed to the MessagingClient constructor, ensuring that credentials are not hard-coded or stored in an unsecure manner. See Example 3-1 for more details about configuring SAML security in a UMS web service client.
For more information about securing web services using Oracle Web Services Manager see Securing Web Services and Managing Policies with Oracle Web Services Manager.
Username token and SAML token security are also supported for the Listener callback web services. When registering a listener, the client application must supply additional parameters specifying the security policy and any key or credential lookup information that the server requires to establish a secure connection.
Example 3-11 illustrates how to establish a secure callback endpoint using username token security:
Example 3-11 Establishing a Secure Callback Endpoint Using Username Token Security
MessagingClient client = new MessagingClient(clientParameters);
...
ListenerReference listenerRef = new ListenerReference();
// A web service implementing the oracle.ucs.messaging.ws.Listener
// interface must be available at the specified URL.
listenerRef.setEndpoint(myCallbackURL);
Parameter policyParam = new Parameter();
policyParam.setName(ClientConstants.POLICY_STRING);
policyParam.setValue("oracle/wss11_username_token_with_message_protection_client_policy");
listenerRef.getParameters.add(policyParam);
// A credential store entry with the specified key must be
// provisioned on the server side so it will be available when the callback
// is invoked.
Parameter csfParam = new Parameter();
csfParam.setName(oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_CSF_KEY);
csfParam.setValue("callback-csf-key");
listenerRef.getParameters.add(csfParam);
client.setMessageListener(listenerRef);
Instances of the Web Services MessagingClient class are not thread-safe due to the underlying services provided by the JAX-WS stack. You are responsible for ensuring that each instance is used by only one thread at a time.