The UMS API provides a plain old java (POJO/POJI) programming model and this eliminates the needs for application developers to package and implement various Jakarta EE modules (such as an EJB module) in an application to access UMS features.

This reduces the complexity of the client application, and also, reduces application development time because developers can create applications to run in a Jakarta EE container without performing any additional packaging of modules, or obtaining specialized tools to perform such packaging tasks.

Consumers do not need to deploy any EJB or other Jakarta EE modules in their applications, but must ensure that the UMS libraries are available in an application' s runtime class path. The deployment is as a shared library, oracle.sdp.client.

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

The MessagingClient object is essential to the UMS Java API user. This object is used to, for instance, send a message, retrieve status information for a sent message, and to receive messages synchronously. The MessagingClient object is created using the MessagingClientFactory.createMessagingClient() method.

Client applications can specify a set of parameters at runtime when instantiating a MessagingClient object. For example, you configure a MessagingClient instance by specifying parameters as key-value pairs in a java.util.Map<String, Object>. Among other things, the configuration parameters serve to identify the client application, point to the UMS server, and establish security credentials. Client applications are responsible for storing and loading the configuration parameters using any available mechanism.

The MessagingClient needs to be released when the application stops or undeployes, or when the EJB bean that uses the client destroyes.

Table 2-1 lists some configuration parameters that may be set for the Java API. In typical use cases, most of the parameters do not need to be provided and the API implementation uses sensible default values.

To release resources used by the MessagingClient instance when it is no longer needed, call MessagingClientFactory.remove(client). If you do not call this method, some resources such as worker threads and JMS listeners may remain active.

Example 2-1 shows a sample code for creating a MessagingClient instance:

Map<String, Object> params = new HashMap<String, Object>();
// params.put(key, value);  // if optional parameters need to be specified.
MessagingClient messagingClient = MessagingClientFactory.createMessagingClient(params); 

A MessagingClient cannot be reconfigured after it is instantiated. Instead, you must create a new instance of the MessagingClient class using the desired configuration.

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

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

There will be one status object per recipient that contains status information, which helps you understand if the message is pending, if the message was sent successfully, if the message was failed to send, if there are failover addresses, and if the message is automatically resent.

• Synchronous Retrieval of Message Status
  
• Asynchronous Receiving of Message Status
  

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 in-queue of the application that registered the matching access point. From the application perspective there are two modes for receiving a message from its in-queue, synchronous and asynchronous.

• Registering an Access Point
  
• Synchronous Receiving
  
• Asynchronous Receiving
  
• Message Filtering
  

The 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. The following rules apply:

• Two client applications are considered to be instances of the same application if they use the same ApplicationName configuration parameter when creating the UMS Messaging Client. If not set explicitly, UMS will use the client application's deployment name as the ApplicationName.

• Instances of the same application share most of their configuration, and artifacts such as Access Points and Message Filters that are registered by one instance are shared by all instances.

• The ApplicationInstanceName configuration parameter enables you to distinguish instances from one another. Typically this parameter is synthesized by the API implementation, and does not need to be populated by the application developer. Refer to the Javadoc for cases in which this value must be populated.

• Listener correlators are instance-specific. If two different instances of an application register listeners and supply different correlators, then when instance A's listener is invoked, correlator A is supplied; when instance B's listener is invoked, correlator B is supplied.

UMS provides support for XA enabled transactions for outbound and inbound messages. The industry standard, X/Open XA protocol, is widely supported in other Oracle products such as Business Process Management (BPM).

• About XA Transactions
  
• Sending and Receiving XA Enabled Messages
  

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 Java 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 = message.getMessageInfo();
msgInfo.setMaxResend(1);
String mid = messagingClient.send(message);

When you examine the status of a sent message as explained in Retrieving Message Status, you get information about both the failover chain and the resends by calling getTotalFailovers()/getFailoverOrder() and getMaxResend()/getCurrentResend() on the Status object. 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. When maxResend equals currentResend and failover order equals total failovers then the resend and failover chain is completely exhausted.

For more information about setMaxResend, getTotalFailovers , getFailoverOrder, and other methods, see User Messaging Service Java API Reference.

Unless multiple drivers of the same type is used, the UMS Server engine selects a driver based on the delivery type that is defined in the UMS Message sent by the client application.

For example, in a message, if the recipient address is "EMAIL:john@example.com" the Email driver is selected, if the recipient address is "SMS:1234" the SMS driver is selected, if the recipient address is "uri:twitter" then, Twitter driver is selected and so on.

The DeliveryType enum defines the delivery channel for a message. For more information, see User Messaging Service Java API Reference.

However, if the system topology requires multiple instances of a driver, for instance, two Email drivers configured with different Email servers, the outgoing UMS Message can be created in such a way that a specific driver is selected by the UMS Server engine. To do this, you must ensure that the following properties for the message in the client application maps to the UMS Driver configuration settings:

For more information about the driver configuration parameters, see "Configuring User Messaging Service Drivers" in Administering Oracle User Messaging Service.

In certain circumstances such as a high load, you may benefit from specifying UMS Message priority when sending a message.

The message priority is used in the internal JMS queues. Also, if the protocol implemented by the driver supports priority, the UMS Message priority is translated to the corresponding protocol priority. Specify the priority as illustrated in the following example:

MessageInfo msgInfo = message.getMessageInfo();
msgInfo.setPriority(MessagePriorityType.HIGH);
String mid = messagingClient.send(message);

For information about all available priority types, see MessagePriorityType definition in User Messaging Service Java API Reference.

The expiration time can be set for a message if the message is only valid for a limited period of time. Note that it depends on the underlying messaging protocol if the expiration setting is honored or not, see table Table 2-3

MessageInfo msgInfo = message.getMessageInfo();
msgInfo.setExpiration(3600);
String mid = messagingClient.send(message);

Table 2-3 shows which drivers, that is, underlying messaging protocols, that support message priority and/or message expiration:

User Communication Preferences are invoked for recipient addresses that contains the USER prefix (for example, USER:john.doe). The preferences can be partitioned into profiles.

Below is an example of how to specify a profile when sending a message:

Address recipient = MessagingFactory.createAddress("USER:john.doe");
message.addRecipient(recipient);
MessageInfo msgInfo = message.getMessageInfo();
msgInfo.setProfileId(“myProfileId");
String mid = messagingClient.send(message);

For information about User Communication Preferences and profiles, see Administering User Communication Preferences.

Client applications may need to specify one or more additional configuration parameters to establish a secure listener.

For more information, see Table 2-1.

Client applications that use the UMS Java API are usually multi-threaded. Typical scenarios include a pool of EJB instances, each of which uses a MessagingClient instance; and a servlet instance that is serviced by multiple threads in a web container.

The UMS Java API supports the following thread model:

• Each call to MessagingClientFactory.createMessagingClient returns a new MessagingClient instance.

• When two MessagingClient instances are created by passing parameter maps that are equal to MessagingClientFactory.createMessagingClient, they are instances of the same client. Instances created by passing different parameter maps are instances of separate clients.

• An instance of MessagingClient is not thread safe when it has been obtained using MessagingClientFactory.createMessagingClient. Client applications must ensure that a given instance is used by only one thread at a time. They may do so by ensuring that an instance is only visible to one thread at a time, or by synchronizing access to the MessagingClient instance.

• Two instances of the same client (created with identical parameter maps) do share some resources – notably they share Message and Status Listeners, and use a common pool of Worker threads to execute asynchronous messaging operations. For example, if instance A calls setMessageListener(), and then instance B calls setMessageListener(), then B's listener is the active default message listener.

The following are typical use cases:

• To use the UMS Java API from an EJB (either a Message Driven Bean or a Session Bean) application, the recommended approach is to create a MessagingClient instance in the bean' s ejbCreate (or equivalent @PostConstruct) method, and store the MessagingClient in an instance variable in the bean class. The EJB container ensures that only one thread at a time uses a given EJB instance, which ensures that only one thread at a time accesses the bean' s MessagingClient instance.

• To use the UMS Java API from a Servlet, there are several possible approaches. In general, web containers create a single instance of the servlet class, which may be accessed by multiple threads concurrently. If a single MessagingClient instance is created and stored in a servlet instance variable, then access to the instance must be synchronized.

  Another approach is to create a pool of MessagingClient instances that are shared among servlet threads.

  Finally, you can associate individual MessagingClient instances with individual HTTP Sessions. This approach allows increased concurrency compared to having a single MessagingClient for all servlet requests. However, it is possible for multiple threads to access an HTTP Session at the same time due to concurrent client requests, so synchronization is still required in this case.

• Listener Threading