Message class
The Message class provides methods to:
- Cause the creation and destruction of messages.
- Set and retrieve message content.
- Set and retrieve metadata properties of messages.
A Message object represents a reference to a message being passed through the system engine. The message itself belongs to the system engine.
There is no public constructor for a message; instead, a Message
object is obtained from the system engine, represented as a CloverEnv
.
The system engine communicates with a TPS writer primarily by Message objects.
- If a Java UPoC creates a new message, then it does not own the resources associated with that message.
- If a Java class creates a message
in a TPS, then the engine must be instructed on how to treat that message. It
does this with a
DispositionList
or by destroying it.
Failure to do one represents a resource leak.
The GRM class (Generic Record Manager) also provides a standard method to create a new message based on a GRM instance. Conversely, the Message class includes standard methods to create instances of GRM subclasses based on a message.
A Java UPoC can remember a reference to a message between method invocations, for example, using a class variable. The programmer must be aware that the Message object in Java is not the same thing as the underlying message in the engine. The message in the engine does not depend on Java reference counting of the Message object in Java.
For example, a Java TPS creates a message, and does not specify a disposition for that message when returning a disposition list. Then, the engine takes no action on that message. It is valid for the TPS to include the message in a later disposition list. This is a common technique often used to consolidate or match messages.
An exception results if a message that is added to one disposition list is added to the disposition list returned by a later invocation to process.
The underlying messages are processed by the engine, and possibly by user code that is written in languages other than Java. The life cycle of a message is not controlled by the JVM.
The message contents are accessed or set as a String or as a byte array. Message content is a valid UTF-8 format if the String methods are used. Conversion between the UTF-8 representation in the message and the String representation seen by the Java API programmer is performed by the system, not the JVM.