Sending and Receiving Messages using the User Messaging Service Web Service API

3 Sending and Receiving Messages using the User Messaging Service Web Service API

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.

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

Introduction to the UMS Web Service API
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.
Creating a UMS Client Instance and Specifying Runtime Parameters
The MessagingClient object is the fundamental UMS API object that you must create in the Client application using the UMS Web Service API.
Sending a Message
Invoking the send method of MessagingClient object sends the message in a Web Service request to the UMS Server, where it is processed accordingly.
Retrieving Message Status
After sending a message, you can use Oracle UMS to retrieve the message status either synchronously or asynchronously.
Receiving a Message
This section describes how an application receives messages.
Configuring for a Cluster Environment
The UMS Web Services API supports an environment where client applications and the UMS server are deployed in a cluster environment.
Using UMS Web Service API to Specify Message Resends
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.
Configuring Security
This section contains information related to configuring security.
Threading Model
Instances of the Web Services MessagingClient class are not thread-safe due to the underlying services provided by the JAX-WS stack.

Introduction to the UMS Web Service API

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

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

Creating a UMS Client Instance and Specifying Runtime Parameters

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
`javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY`	String	Endpoint URL for the remote UMS WS. This is typically "http://<host>:<port>/ucs/messaging/webservice".
`javax.xml.ws.BindingProvider.USERNAME_PROPERTY`	String	Username to be asserted in WS-Security headers when relevant
`oracle.ucs.messaging.ws.ClientConstants.POLICIES`	String[]	Array of OWSM WS-Security policies to attach to the client's requests. These must match the policies specified on the server side.
`oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY`	String	Used for OWSM policy attachment. Specifies an alternate alias to use for looking up encryption and signing keys from the credential store.
`oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_CSF_KEY`	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".

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

Sending a Message

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.

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

Creating a Message

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

Parent topic: Sending a Message

Creating a Plaintext Message

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

Parent topic: Creating a Message

Creating a Multipart/Mixed Message (with Text and Binary Parts)

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()));

Parent topic: Creating a Message

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

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()));

Parent topic: Creating a Message

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

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

Parent topic: Creating a Message

API Reference for Interface Message

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

Parent topic: Sending a Message

API Reference for Enum DeliveryType

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

Parent topic: Sending a Message

Creating an Address

For information about the types of addresses and to understand how to create Address objects and to define failover address, see Creating an Address.

See User Messaging Service Java API Reference to know more about the Address interface.

Parent topic: Sending a Message

Recipient Types

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.

Parent topic: Creating an Address

API Reference for Class MessagingFactory

See User Messaging Service Java API Reference for information about the class MessagingFactory.

Parent topic: Creating an Address

User Preferences in Messages

When you create a message using WS API, you can also supply facts for business terms for the user preferences in that message. See User Preference Based Messaging for more details.

Parent topic: Sending a Message

Retrieving Message Status

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

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

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

Parent topic: Retrieving Message Status

Asynchronous Receiving of Message Status

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

Parent topic: Retrieving Message Status

Creating a Listener

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!");
  }
}

Parent topic: Asynchronous Receiving of Message Status

Publish the Callback Service

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):

Example 3-7 Publish the Callback Service

Listener myListener = new MyListener();
String callbackURL = "http://host:port/umswscallback";
Endpoint myEndpoint = javax.xml.ws.Endpoint.publish(callbackURL, myListener);

Parent topic: Asynchronous Receiving of Message Status

Stop a Dynamically Published Endpoint

To stop a dynamically published endpoint, call the stop() method on the Endpoint object returned from Endpoint.publish() (Example 3-8).

Example 3-8 Stop a Dynamically Published Endpoint

// When done, stop the endpoint, ideally in a finally block or other reliable cleanup mechanism
myEndpoint.stop();

Parent topic: Asynchronous Receiving of Message Status

Registration

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.

Parent topic: Asynchronous Receiving of Message Status

Receiving a 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.

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

Registering an Access Point

AccessPoint represents one or more device addresses for receiving incoming messages. For more details about access points, see Registering an Access Point.

Parent topic: Receiving a Message

Synchronous Receiving

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

Parent topic: Receiving a Message

Asynchronous Receiving

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 Jakarta EE servlet module. However, a servlet-based listener implementation is also acceptable.

Parent topic: Receiving a Message

Creating a Listener

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.

Parent topic: Asynchronous Receiving

Default Message Listener

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.

Example 3-9 Default Message Listener

ListenerReference listenerRef = new ListenerReference();
listenerRef.setEndpoint("url_to_your_webservice_message_listener");
messagingClient.setMessageListener(listenerRef);

Parent topic: Asynchronous Receiving

Per Access Point Message Listener

The client application can also register an access point and specify a Listener object and an optional correlator object (Example 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);

Parent topic: Asynchronous Receiving

Message Filtering

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 Message Filtering.

Parent topic: Receiving a Message

Configuring for a Cluster Environment

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 Configuring for a Cluster Environment.

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

Using UMS Web Service API to Specify Message Resends

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.

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

Configuring Security

This section contains information related to configuring security.

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API

Client and Server Security

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.

Parent topic: Configuring Security

Listener or Callback Security

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

Parent topic: Configuring Security

Threading Model

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.

Parent topic: Sending and Receiving Messages using the User Messaging Service Web Service API