5 Initiating Transformations Using the Java API

The Java API consists of several JAR files that need to be included in any third-party product. These files include the API JAR file, as well as several JAR files needed by the API. Example programs are supplied with the API to demonstrate the use of various Transformation Server features, but are not required to be included with any third-party applications.

Please note that you should be running Java version 1.4.1 or higher if you plan to use the Java API for Transformation Server. Also just to note, GNU java (gij) is not supported.

This chapter includes the following sections:

Section 5.1, "Key Packages"
Section 5.2, "Key Classes"
Section 5.3, "Redirected IO"
Section 5.4, "Sample Applications"

5.1 Key Packages

The Java API for Transformation Server consists of classes from several packages. The packages are as follows:

com.outsideinsdk.tsapi.api: Contains the main API classes, which all applications will need.
com.outsideinsdk.tsapi.api.option: Contains classes used for setting common options in Transformation Server.
com.outsideinsdk.tsapi.api.option.hwx: Contains classes used for setting options related to the Export engine.
com.outsideinsdk.tsapi.api.option.xsd: Contains classes used for setting common SOAP options.
com.outsideinsdk.tsapi.api.message: Contains classes used to represent messages returned from Transformation Server.
com.outsideinsdk.tsapi.api.redirect: Contains classes used for redirected IO.

5.2 Key Classes

While the Java API incorporates many classes, there are some classes that developers will need to use more than others, and therefore should be more familiar with.

com.outsideinsdk.tsapi.api.TransformClient: This class is the bulk of the API. A connection to an instance of Transformation Server is created by instantiating an instance of this class. All calls to the server go through this class. Every Transformation Server application will need at least one instance of TransformClient.
com.outsideinsdk.tsapi.api.option.xsd: This class is the base class of all option classes. Applications won't instantiate this class directly, but through the use of other option classes.
com.outsideinsdk.tsapi.api.option.xsd.BooleanOption

com.outsideinsdk.tsapi.api.option.xsd.FloatOption

com.outsideinsdk.tsapi.api.option.xsd.IntegerOption

com.outsideinsdk.tsapi.api.option.xsd.LongOption

com.outsideinsdk.tsapi.api.option.xsd.StringOption

com.outsideinsdk.tsapi.api.option.xsd.UnsignedIntOption

These classes are used as substitutes for native objects when used as option values.

The UnsignedIntOption class is a wrapper for a Long value. The reason for this is that several options in Transformation Server require unsigned integers as values, but Java does not support this type. For this reason, the Java API reads the value and interprets it as the larger Long type.
com.outsideinsdk.tsapi.api.option.StringData: The StringData class is different than the StringOption class. It includes a field for the character set to be specified, and also allows the actual bytes storing the string to be Base64 encoded. This class is used many times in the Java API.
com.outsideinsdk.tsapi.api.option.IOSpec: This class is used for all file specifications. It consists of a StringData object specifying the path to the file, and a string that specifies the path type. Currently supported path types are path and redirect. IOSpec objects with a path type of path are expected to be accessible locally by Transformation Server, while IOSpec objects with a path type of redirect use redirected IO to allow the server to access files on the client machine.
com.outsideinsdk.tsapi.api.redirect.BaseIO: This interface is used to allow the Java API to interact with redirected IO sources. Through this interface, developers provide a common interface to their data so that the Java API can perform any required IO operations. A default implementation is provided in the example code.
com.outsideinsdk.tsapi.api.redirect.OpenIO: This class is the interface through which the Java API is able to open files for redirected IO. Any third-party implementation that wishes to incorporate redirected IO must implement this interface. A default implementation is provided in the example code.
com.outsideinsdk.tsapi.api.redirect.IOProvider: This class is used as a registry for the OpenIO class. When an application is using redirected IO, the implementation of the OpenIO interface must be registered with the IOProvider class through the static register() method.

5.3 Redirected IO

Transformation Server allows developers to specify how IO should be performed. Currently, Transformation Server handles three types of IO natively; file system, URL and redirected IO. When specifying the path using the type path, Transformation Server treats the file specification as a path to a file on the local file system. When specifying the path using the type url, Transformation Server treats the file specification as an Internet address. A path type of redirect allows the developer more control over the IO functions.

Redirected IO allows file IO operations to be done remotely. Further, redirected IO allows the developer to control all aspects of the actual IO operations. Through the use of the BaseIO and OpenIO interfaces, developers can take control of all IO operations. To accomplish this, developers need to supply the Java API with an implementation of the OpenIO interface. This is achieved by calling IOProvider.register(), and passing it an instance of the OpenIO implementation.

When the Java API receives a request for an IO operation, it first checks to see if the file has been opened. If it has not, it calls the openIO() method in the OpenIO implementation, passing it the IOSpec and an OpenIOFlag object. This method is expected to return an instance of a BaseIO implementation that will allow the Java API to perform all necessary IO operations. Once the file has been opened, all communication occurs directly between the Java API and the BaseIO implementation. See the following diagram for further explanation.

Figure 5-1 Java API

Graphic providing a flowchart view of the Java API

5.4 Sample Applications

The folowing sections contains sample applications.

5.4.1 TSJavaDemo

The class com.outsideinsdk.tsapi.example.TSJavaDemo is a sample application that uses several helper classes to demonstrate the uses of the Transformation Server Java Client API. It takes several parameters from the command line and optionally reads a text-based file containing transformation options. These are then passed to Transformation Server via the Java Client API to execute the transformation. A batch file called tsjavademo (located in sdk\[platform name]\sdk\samplecode\tsjavademo) is provided for convenient access to this application.

This application simply creates a TransformClient object, calls doTransform() on that object, and then prints the result. While this is a very simple example, it clearly shows the required steps for executing a transformation using Transformation Server's Java API.

Please note that all path types referred to in the following documentation are dependent on the setting for the -t option. The default value for the -t parameter is p, meaning that paths are relative to the tsmanager executable on the machine which is hosting it.

The available command line parameters are as follows:

-s, -server : The host name or IP address where Transformation Server is running. (Required)
-p, -port: The port number on which Transformation Server will accept connections. (Required)
-i, -input: The path/URL to the input file. This parameter requires either an absolute path to a file, or a path to a file that is relative to Transformation Suite's root install directory. To use an input path relative to the tsjavademo sample app, the -t r (redirected IO) option should be used. (Required)
-o. -output: The path/URL to the output file. (Required)
-r, -format: The desired output format. This value comes from the agent_engine_list.xml file in the root level of the install directory. (Required)
-f, -optionFile: The option file, which can be a *.cfg file, readable by tsdemo, or an XML file. This file must be relative to tsjavademo on the computer sending the request. (Optional)
-n, -optionSetName: The option set from the file in -f, if it is an XML file. (Optional)
-t, -ioType: The type of IO specification used for the input and output parameters. May be a file system path (p), redirected (r), or URL (u). Default is p. Note for HTML Export: Even when u is specified for this parameter, tsjavademo still expects a file path for the template and not a URL path. This path is relative to tsmanager on the computer receiving the request. (Optional)
-h, -help: Shows this list of parameters.

5.4.1.1 Notes on the Sample Application

The source code for this application is provided. It is designed to demonstrate the use of the Transformation Server and the SCCTS module. It is freely modifiable, but is not warranteed and should not be assumed to be of commercial quality.
This application demonstrates the use of custom IO Providers (also referred to as redirected IO). The redirected IO code does nothing more than implement a thin layer on top of the file system input and output. As a result, the file specifications for this example of redirected IO is identical to normal file system paths (unless the URL IO type is chosen, in which case the file specification must be a URL, not a file system path).
In order to transform documents, this application requires Transformation Server (tsmanager) to be running and accessible via TCP/IP.

5.4.2 URL Input and Output

When the paths for input and output files are specified as URLs (ioType parameter equals u), the output files will be sent to the output URL via the HTTP PUT command. In order for this to work correctly, the Web server hosting the output URL must be configured to allow writing to the output URL path.

5.4.3 Redirected Input and Output

When the paths for input and output files are specified as "redirected" (ioType parameter equals r), the sample application will demonstrate how custom objects can be used in place of system calls to provide reading and writing of input and output files. To do so, the developer must implement the BaseIO and OpenIO interfaces.

The sample BaseIO implementation is the following:

com.outsideinsdk.tsapi.example.BaseIOExample

The sample OpenIO implementation is the following:

com.outsideinsdk.tsapi.example.OpenIOExample

These two interface implementations demonstrate how developers can implement redirected IO in their own applications. For the Java Client API to make use of these objects, a call is made to IOProvider.register() (registering the OpenIOExample implementation class) and the IOSpec spec types are set to redirect.