3 Sample Applications
Note:
To use Transformation Server, you will need to set the TSROOT variable to the location of the Transformation Server installed SDK. For example, for a Linux version of Transformation Server, you would set:TSROOT=/user/jsmith/ts/ts_linux-x86-32_sdk/sdk.
This chapter includes the following sections:
3.1 Building the Samples on a Windows System
Microsoft Visual Studio 2010 files are provided for building each of the sample applications.
Because .vcxproj files may not pick up the right compiler on their own, you need to make sure that you are building with the correct configuration in Visual Studio 2010 or higher.
The project files for the sample applications can be found in the \sdk\samplecode\win subdirectory of the Oracle Outside In SDK.
For specific information about building the sample applications on your UNIX OS, see UNIX Implementation Details.
3.2 An Overview of the Sample Applications
Here's a quick tour of the sample applications provided with this product. Not all of the sample applications are provided for both the Windows and UNIX platforms. See the heading of each application's subsection for clarification.
This section includes the following sample applications:
3.2.2 batch_process_sx
batch_process_sx demonstrates running Search Export in a separate process on multiple input files. It also allows the timing of each run.
The application is executed from the command line and takes several possible parameters:
batch_process_sx -f inputfile -o outputfile or [-d inputdir -o outputdir] [-i iterations] [-q[2]] [-b]
-
-f specifies the name of a single input file.
-
-d specifies the name of an input directory of files.
-
-o specifies the name of an output file if -f is being used, or the name of an output directory if -d is being used.
-
-i is an optional parameter specifying the number of iterations to perform.
-
-q and -q2 diminish the output to the screen.
-
-b increases the amount of content in the output including processing tags and sub-documents.
3.2.3 export (Windows Only)
This application was designed to facilitate the testing of the software and should not be assumed to be of commercial quality.
Note:
No default options are set at initial runtime. The time the software is used, click the Options button and set the options. Failure to do this generates export errors.
The application allows the user to run a single source file. The user can choose the source file, an output file and set the various options.
3.2.3.1 The Export Main Window
The following figure shows the Main Window for the export application.
Figure 3-1 Export Main Window for Search Export
![export Main Window for Search Export export Main Window for Search Export](img/sxport_one.gif)
The Main Window is composed of several elements, discussed here.
-
Output Format menu: This menu allows the user to select the type of output to generate. An entry for the format(s) you license will appear in this drop-down menu
-
Options button: This opens up a new dialog with one or more tabs exposing the options for the selected product.
-
Source document field: This is the document to be exported. Use the Browse button to pick the source file, or type in the path name.
-
'Export to' Field: This is the initial resulting output file. Type in a file name or use the Browse button to choose a file. Other output files are named based on the one chosen here.
-
Delete button: Clicking this button deletes all files generated by the last export, listed in the Status: field. This is useful when multiple output files are produced because the default naming rules do not overwrite an existing file. If you run Export over and over again with the same output file name, you can produce a large number of files. Clicking Delete before each export solves this problem.
-
'After Export, view output file with default application' checkbox: If the export was successful, checking this box launches the initial output file in the application associated with the output flavor's default extension.
-
Export button: Click this button to start the export process once you've determined the export settings.
-
Exit button: Click to close the Export application.
3.2.4 exsimple
This simple command line driven program allows the user to run a single source file through the software. The user can choose the source file, an output file and set the various options.
To run the program, type:
exsimple in_file out_file config_file
-
in_file is the input file to be converted
-
out_file is the output location
-
config_file is the configuration file that sets the conversion options. If no configuration file is specified, default.cfg in the current directory is used.
The configuration file is a text file used to set the conversion options. We recommend reading through the configuration file for more information about valid options and their values (use of invalid options results in exsimple not producing output).
Follow these instructions to set configurable options:
-
Set the Output ID to FI_SEARCHML_LATEST before running the software. It is required and must not be omitted.
3.2.5 extract_archive
extract_archive demonstrates using the DATree API to extract all nodes in an archive.
The application is executed from the command line and takes two parameters, the name of the input file and the name of an output directory for the extracted files:
extract_archive input_file output_directory
3.2.6 process_isolate
process_isolate demonstrates running SX in a separate process. Due to the socket usage, there are different versions for Windows and Unix.
The application is executed from the command line and takes only one parameter, the name of the input file:
process_isolate_sample_unix -f input_file process_isolate_sample_win -f input_file
3.2.7 xxredir (Search Export)
This sample application is based on the exsimple sample application. It is designed to demonstrate how to use redirected IO and callbacks when using the software. It takes the same arguments and command line structure as exsimple and the same configuration files can be used. For details, see exsimple.
3.3 Accessing the SDK via a Java Wrapper
The ExJava Java wrapper, working in tandem with the exporter sample application, provides a working example of one method of interfacing with Oracle's C-based SDK products from a Java application. Export.jar is a Java API wrapper used by a Java application to control the exporter executable and set conversion options. exporter is a C-based executable which performs conversions using the modules in the Oracle Outside In SDK.
The exporter executable should be placed in the root directory of the Oracle Outside In SDK being used. If more than one Oracle Outside In SDK is being used, the contents of each SDK should be unpacked to the same root directory. Export.jar should be placed somewhere in your classpath.
On UNIX systems this sample application must be run from the directory containing the Oracle Outside In technology.Java version 1.6 or higher is required to run this sample application.
This section covers the following topics:
3.3.1 The ExJava Wrapper API
The JavaDocs documentation for the Java API is provided in the /sdk/samplecode/ExJava/docs directory. Conversion options are set using the ExportProperties.
Additionally, the appropriate .cfg file for the ExportTest sample application found in the Examples/ExportTest directory may provide further insight as to what properties are available and how they correspond to options and values for options.
The Export.jar and its source code can be found in the Java API directory. Place Export.jar somewhere in your classpath. In order to use the ExportTest sample application (which demonstrates how a Java application can use the ExJava API) without modifying your system configuration or the ExJava sample application, you should place the Export.jar file in the root directory of the Oracle Outside In SDK product you are using.
3.3.2 The C-Based Exporter Application
This is a standalone executable that runs out of process from the Java API. The Java API controls the conversion through command line parameters that are passed to the executable. After the conversion completes, the executable returns a conversion status code to the Java API. The command line parameters are base-64 encoded to allow for the use of Unicode encoded paths.
As the exporter executable is a C-based application, you will need to make sure the Java API can find the version of exporter appropriate for the platform you are using. Generally, and specifically for the purpose of using the ExportTest sample application, the correct executable should be copied to the root directory of the Oracle export SDK product you are using.
A compiled version of the C exporter program is included in the SDK with the rest of the Oracle Outside In binaries. The source for exporter is located in the /sdk/samplecode/ExJava/exporter directory.
The current implementation of ExJava may not produce an error if it cannot find the exporter application. This known issue may be corrected in a future version of ExJava.
3.3.3 Compiling the Executables
A Microsoft Visual Studio 6.0 project file and a UNIX makefile are provided in /sdk/samplecode/ExJava/exporter/win and /sdk/samplecode/ExJava/exporter/unix, respectively, so that you can modify the exporter executable or compile it for a platform other than those for which compiled versions of exporter are provided. If you unpacked the ExJava package into the root directory of one of Oracle's export SDK products, you should be able to use the Visual Studio Project and makefile as is. Otherwise, you will need to edit them in order to provide paths to the Oracle export SDK include and library files.
If you are compiling ExJava for use on the Solaris platform, make sure your LD_LIBRARY_PATH contains the Oracle Outside In SDK path before trying to build the exporter module.
3.3.4 The ExportTest Sample Application
ExportTest is an example of how a Java developer could use the ExJava wrapper to use one of the Oracle Outside In SDKs. The following is a list of the components that should be placed in the root directory of the Oracle Outside In SDK you are using in order to run this sample application:
-
Export.jar (from the Java API directory)
-
Exporter module for the platform you wish to use (located in the /sdk/samplecode/ExJava/exporter/win or /sdk/samplecode/ExJava/exporter/unix directory, depending on which platform you are using)
-
sx.cfg (also in Examples/ExportTest directory)
-
If you are running ExportTest on a UNIX system, make sure to edit the .cfg file so it reflects the correct name of the exporter module you renamed.
-
ExportTest.jar (also in Examples/ExportTest directory)
-
The appropriate batch file to run the ExportTest application (ExportTest.bat for Windows and ExportTest.sh for UNIX, both located in the Examples/ExportTest directory)
Once these files are properly copied, execute the batch file with the name/path of an input file to convert, the name for the base output file and the name of the configuration file to use for setting conversion options.
ExportTest.jar uses the contents of the configuration file to determine what option/value pairs it should use when doing the conversion. It is not necessary to use a configuration file when developing your own application if you so choose not to.
3.3.5 An Example Conversion Using the ExJava Wrapper
This is a simple outline of the steps for using the ExJava wrapper on a Windows system to convert a Word document called MyWordDoc.Doc. If you are using a UNIX system, see UNIX Implementation Details for information about properly setting up your environment to use the Oracle Outside In SDK:
-
Edit the .cfg file and make sure outputid is set to the FI* value appropriate for the Oracle Outside In product you've licensed. Alter any other parameters in the .cfg file as needed then save the file.
-
Execute the following command. The sample command below assumes XML as the export type. Change this type accordingly:
ExportTest.bat myworddoc.doc output.xml sx.cfg