Utility and convenience methods

CloverEnv provides utility methods which can assist the API programmer.

Log method

This method permits the API programmer to incorporate diagnostic or audit output in the output log of the system engine.

The log’s verbosity level is controlled at run-time without the Java API programmer having to change code. The log method has a verbosity argument that determines whether it is actioned at run-time, depending on environment and engine settings.

Note: The method invocation is made even if no output is produced. This is subject to any dynamic compile optimization in-lining provided by the JVM. There is still some overhead that is associated with each log statement left in production code.

For example:

cloverEnv.log(50, "Message contents now >" +
        msg.getContent() + "<");

This produces a line in the engine log similar to this, if the verbosity environment is set for 50 or above:

23/04/09 16:52:05 - 50 - Message contents now >This is a message<

Tcl evaluation from Java

Tcl (Tool Command Language) is a richly-featured scripting language. This is the primary language used to write system UPoCs. Java API programmers can invoke a Tcl piece to take advantage of inbuilt Tcl functionality. Or, an existing Tcl procedure written for their site can be used.

Tcl works by evaluating commands that have zero or more arguments and optionally returning a value.

The tclEval method of CloverEnv requests the engine to evaluate a Tcl command and returns any return value. Any error that is generated in the Tcl evaluation causes a CloverleafException to be thrown.