Calling a Java XLT from Tcl

The relevant Tcl extensions are makeUpocInstance, processXLT, and destroyUpocInstance.

These can be used directly, or pre-provided procs cljXLTObjects and cljXLTStrings, which are themselves XLT style interfaces, can be used to wrap them. Usually, the wrapping is adequate. At times, though, the Java UPoC instances that are created implicitly through the wrapper are destroyed until the Tcl interpreter shuts down.

The procs require a single argument that is a keyed list. This must include a key CLASS which has the fully-qualified name of the XLT subclass to be used. They also require a key XLT_STYLE that determines which method of the Java XLT is called. The keyed list must also match any PropertyTree keys that the Java UPoC is expecting.

The relationship between theXLT_STYLE and the method is:

  • Link procedure name: cljXLTStrings
    • XLT_STYLE: CALL

      Method: process

    • XLT_STYLE: SINGLE

      Method: xlateString

    • XLT_STYLE: VECTOR

      Method: xlateStrings

  • Link procedure name: cljXLTObjects
    • XLT_STYLE: CALL

      Method: process

    • XLT_STYLE: SINGLE

      Method: xlateObject

    • XLT_STYLE: VECTOR

      Method: xlateObjects

A SINGLE style only results in a method invocation if there is at least one input value to the translate action.

A VECTOR style always result in a method invocation.

If there are no input values to the translate action, then the vector that is passed in has zero elements.

An example (ignore wrap-around and new lines) which calls the xlateStrings method of lnysample.Split_Text_XLT is:

cljXLTStrings {CLASS lnysample.Split_Text_XLT} 
                                {CHUNKSIZE 35} 
                                {XLT_STYLE VECTOR}

The XLT interface uses upvars. Therefore, if cljXLT procs are called from within another XLT, they directly set the xlateOutVals, and so on, in the calling procedure.