Ultra Messaging (Version 6.16.1)
Introduction
This document provides detailed reference information for the UM Java API.
For policies and procedures related to Ultra Messaging Technical Support, see UM Support.
(C) Copyright 2004,2023 Informatica Inc. All Rights Reserved.
This software and documentation are provided only under a separate license agreement containing restrictions on use and disclosure. No part of this document may be reproduced or transmitted in any form, by any means (electronic, photocopying, recording or otherwise) without prior consent of Informatica LLC.
A current list of Informatica trademarks is available on the web at https://www.informatica.com/trademarks.html.
Portions of this software and/or documentation are subject to copyright held by third parties. Required third party notices are included with the product.
This software is protected by patents as detailed at https://www.informatica.com/legal/patents.html.
The information in this documentation is subject to change without notice. If you find any problems in this documentation, please report them to us in writing at Informatica LLC 2100 Seaport Blvd. Redwood City, CA 94063.
Informatica products are warranted according to the terms and conditions of the agreements under which they are provided.
INFORMATICA LLC PROVIDES THE INFORMATION IN THIS DOCUMENT "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND ANY WARRANTY OR CONDITION OF NON-INFRINGEMENT.
UM Java API
To use the UM Java API, you must access the UM Jar file. It is not included in the the normal UM package file, it is a separate file named: UMS_(um_vers).jar. For example:
- Note
- Although the jar file contains the product name "UMS", this file is intended to be used across all UM products, UMS, UMP, and UMQ. Users of UMP and UMQ should use the UMS jar file.
This jar file uses the Java Native Interface (JNI) to access the UM native libraries. Note that the native libraries are platform dependent and are contained in the platform-specific packages.
Application Callbacks in Java
There are a variety of UM features that include the UM library calling back into the application. The most common example of this is the Receiver callback (sometimes named "onReceive").
It is important that the application callback not allow any unhandled exceptions to be thrown back into UM. For example, you might enclose your entire callback code in an enclosing try/catch. The application callback should always return normally into UM.
See Java Message Reception for more information, including code examples.
Using UM Java on Windows
To run Java applications on Windows, the UM jar file needs to be able to find the native UM library, "lbm.dll". A typical way to accomplish this is to include the "bin" folder in the system PATH. For example:
(Replace "UMS_6.12.1" with your UM version.)
Using UM Java on Unix
To run Java applications on Unix, the UM jar file needs to be able to find the native UM dynamic library, "liblbm.so". A typical way to accomplish this is to set the environment variable "LD_LIBRARY_PATH" to point at the UM library directory. For example:
(Replace "/um_home/UMS_6.12.1/Linux-glibc-2.17-x86_64" with the path where your version of UM is installed.) In there you will find the UM native libraries.
Java Native Interface (JNI)
The UM Java API makes use of the Java Native Interface (JNI) to bridge between the native Java code and the UM library (written in C). This interface provides for two different types of calls: "downcalls" from Java into C, and "upcalls" from C into Java.
Downcalls are relatively inexpensive, although not quite as efficient as a call from one Java method to another. Thus, a Java publisher does not suffer from significantly lower performance than a C publisher.
However, upcalls have a greater expense associated with them. This expense translates directly to increased CPU utilization. This mostly affects subscribers, which have upcalls for received messages. This translates to slightly higher latency and a lower maximum-sustainable throughput.
This Java receiver performance penalty can be mitigated using Receive-Side Batching and, for Linux, Receive Multiple Datagrams.
Garbage Collection
One significant problem with Java performance is garbage collection. While this makes the programmer's life easier, having your application periodically stop doing application-specific useful work to perform its housekeeping duties significantly degrades the overall performance of the application. This is not to imply that garbage collection is not useful work: in the context of Java, it certainly is. But it does nothing to further the goal of the application itself, namely to receive and process data.
Thus, Java performance is inherently unpredictable and can vary significantly from one instant to the next. As an example, consider the lbmrcv example program supplied with UM. Running the C version will show a fairly steady data rate for each sample printed. Running the Java version will show wildly varying data rates for each sample printed. This is due in large part to the periodic interruption of the application to do garbage collection.
See Zero Object Delivery (ZOD) for a UM Java feature that reduces the need for garbage collection.
Zero Object Delivery (ZOD)
UM's Zero Object Delivery (ZOD) feature for Java allows receivers to deliver messages, and sources/receivers deliver events, to an application with no per-message object creation. This lets you write Java sending/receiving applications that require little to no garbage collection at runtime, resulting in lower and more consistent message latencies and hence, better performance.
See Zero Object Delivery for details, including code examples.
Retaining Messages
For lowest latency, received messages should be fully processed directly by the receiver callback. However, there are circumstances where an application needs to save a message for further processing after the receiver callback returns.
See Java Message Reception for details, including code examples.
