Skip Headers
Oracle® Outside In Transformation Server Developer's Guide
Release 8.4.0

Part Number E12868-03
Go to Documentation Home
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

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:

5.1 Key Packages

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

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.

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. 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:


The sample OpenIO implementation is the following:


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.