The UPoC Java package

JVM is part of the system package. You must have JDK to compile Java codes. JDK is not part of the system installation. To use the Java UPoC feature, you must download JDK 6.

Note: During the migration to CIS 6.2 and later versions, the Java UPoCs must be re-complied.

The Java classes in the system's UPoC Java package provide facilities that you can use to manipulate a message within the system engine.

You can customize and extend the behavior of the system engine by specifying user code fragments. The engine runs these fragments at well-defined points in the processing of messages. Sometimes referred to as "hooks" or "user exits," these are formally known as UPoCs (User Points of Control).

As mentioned in the last section, the engine directly invokes UPoC code segments as TcL procedures. To enable supports for UPoCs to written in Java, the engine uses Java Native Interface (JNI) to run Java codes.

Although there are many UPoCs, there are only three interface styles between the engine and the user code:

  • TPS: Controls/extends message movement through the engine.
  • TrxID: Determines a transaction code (routing identifier) for a given message.
  • XLT: Transforms certain fields within a message as part of a transformation specification.

In the Java API, each of these styles is represented as a class which can be extended by the interface developer. To write useful code, the Java programmer makes use of several other classes that are provided within the package com.cloverleaf.Cloverleaf.upoc.

This table lists these classes and the objects that they represent:

Class Objects represented
Message A message passing through the engine. You can modify message content, message metadata, and create new messages.
DispositionList A set of instructions telling the engine what to do with specified messages. The programmer can create new disposition lists.
GRM A Generalized Record Manager, which is a way of addressing specific fields within a message by their logical names. GRM has subclasses for the different types of message layouts supported by the system: FRL, HRL, and VRL messages. The Java programmer can create an empty GRM, set and retrieve field contents from the GRM, construct a GRM from a message, and construct a message from a GRM.
XPM A Translation Pseudo Machine that provides GRM access to a pair of messages. These are the input and output messages of a translation which the engine is processing. An XPM also provides additional functionality not available through a GRM.
PropertyTree A hierarchical properties set. This is similar to a Hashtable or Properties object, but with certain restrictions and certain additional convenience methods. A PropertyTree is used to represent data structures that are not fixed at engine compile time.

For example, the engine can be configured to construct an instance of a newly-developed subclass of TPS without the requirement for an engine recompilation. The new subclass might require certain configuration information. This can be specified in the Network Configuration definition, read by the engine, and passed as a PropertyTree constructor argument to the new subclass.

Another example is in the facility to extend the metadata associated with each message to include additional metadata items not compiled into the engine (USERDATA). The USERDATA of a message is available to the Java programmer as a PropertyTree object.

The methods that are used by the Java programmer also must refer to the system run-time environment within which they are running. A class CloverEnv represents the run-time environment.

Exceptions which stem from incorrect use of the API are represented by exceptions of class CloverleafException.