3 Sample Applications
This chapter describes the sample applications.
Each of the sample applications included in this SDK is designed to highlight a specific aspect of the technology's functionality. We ship built versions of these sample applications. The compiled executables should be in the root directory where the product is installed.
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.
The following copyright applies to all sample applications shipped with this product:
Copyright © Oracle 1993, 2014
All rights reserved.
You have a royalty-free right to use, modify, reproduce and distribute the Sample Applications (and/or any modified version) in any way you find useful, provided that you agree that Oracle has no warranty obligations or liability for any Sample Application files.
This chapter includes the following sections:
3.1 Building the Samples on a Windows System
Microsoft Visual Studio project files are provided for building each of the sample applications. For 32-bit versions of Windows, versions of the project files are provided for Visual Studio 6 (.dsp files) and Visual Studio 2005 (.vcproj files).
Because .vcproj files may not pick up the right compiler on their own, you need to make sure that you are building with the Win64 configuration in Visual Studio 2005. For 64-bit versions of Windows, only the Visual Studio 2005 versions are available.
The project files for the sample applications can be found in the \sdk\samplecode\win subdirectory of the Outside In SDK.
See Chapter 5, "UNIX Implementation Details," for specific information about building the sample applications on your UNIX OS.
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.1 *sample
The name of this sample application varies according to product (xxsample for XML Export).
The following is a basic implementation that uses the default settings for every option.
xxsample Inputfile Outputfile
This sample app provides a very simple demonstration of creating FlexionDoc output.
3.2.2 export (Windows Only)
This application was designed to facilitate the testing of the software and should not be assumed to be of commercial quality.
Important:
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. If you are going to rebuild this application, be sure to set your INCLUDE and LIB paths to the \COMMON and \LIB directories respectively.
3.2.2.1 The export Main Window
The Main Window contains the following fields.
-
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. Pressing Delete before each export solves this problem.
-
'After Export, view output file with default application' Check Box: 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 to start the export process once you've determined the export settings.
-
Exit button: Click to close the Export application.
3.2.3 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_XML_FLEXIONDOC_LATEST before running the software.
3.2.4 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.5 xxredir (XML 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. See "exsimple" for details.
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 Outside In SDK.
The exporter executable should be placed in the root directory of the Outside In SDK being used. If more than one 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 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 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 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 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 Outside In SDKs. The following is a list of the components that should be placed in the root directory of the 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)
-
xx.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 Chapter 5, "UNIX Implementation Details" for information about properly setting up your environment to use the Outside In SDK:
-
Edit the .cfg file and make sure outputid is set to the FI* value appropriate for the 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 xx.cfg
