1. Developer's Guide
  2. Using the Java API
  3. Introduction to the Java API

11 Introduction to the Java API

This chapter provides an introduction to the Java API for PDF Export.

The Java API is an add-on to the Outside In Export SDKs that enables developers to use Java to create applications using Outside In Technology.

This chapter covers the following topics:

11.1 Requirements

To use the API, the following set of modules and tools are required:

  • Java JDK 6 or later

  • The Outside In developer's redistributable modules for your product(s)

  • The API libraries:

    • oilink.jar - The Java library to access the Outside In technologies

    • oilink (on Unix)/oilink.exe (on Windows) - The bridge modules between Java and the C-APIs.

All of the Outside In modules should be in the same directory as oilink.jar.

The SDK includes sample source code to demonstrate how such web applications may be written. These sample applications are written as simply and generically as possible, and will not fill all of the needs of your particular application. They are intended for instructional purposes only.

11.2 Getting Started

There are two steps in developing applications using the APIs. In the first step, you configure the environment to create your application (typical programming tasks not directly related to these APIs); and in the second step, you generate code to utilize the functionality of these libraries.

11.2.1 Configure the Environment

To set up the environment to create a Java application, you need to add the oilink.jar library to your project. (This can be done in Eclipse in the Project Properties dialog by selecting Java Build Path properties > Libraries tab > Add external JARs > browse to oilink.jar.)

11.2.2 Generate Code

Sample application code included with the SDK, OITSample, is a minimal demonstration of how to use this API.

All the functionality required to perform a conversion is provided in an Exporter object. The basic process of exporting a file involves the following tasks:

  1. Create an Exporter object.
  2. Configure the export.
  3. Set the source and primary destination files.
  4. Set the output type.
  5. (Optional) Provide a callback handler.
  6. Run the export.

Tasks 2 through 5 can be done in any order between the first and last task.

11.2.2.1 Create an Exporter Object

To obtain access to the Outside In functionality, you should call the utility function in the "OutsideIn" class. This will provide you an instance of an Exporter Object.

Exporter exporter = OutsideIn.newLocalExporter();
11.2.2.2 Configure the Output

The Outside In API is highly configurable, and presents numerous options to fine-tune the way a document is exported. Each option has a "set" and "get" method to set or retrieve the currently set value.

exporter.setPerformExtendedFI(true);
int timezoneOffset = exporter.getTimeZoneOffset();
11.2.2.3 Set the Source and Primary Destination Files

You are required to specify the source file and the destination file. This is done similarly to setting options using "set" methods.

exporter.setSourceFile(inputFile);
exporter.setDestinationFile(outputFile);

There are other options that can be set at this time to specify the way to handle the input file, such as providing a SourceFormat to provide a mechanism to handle the input file in a different format than that which it is identified as.

The API also supports opening certain types of embedded documents from within an input file. For example, a .zip file may contain a number of embedded documents; and an email message saved as a .msg file may contain attachments. The API provides the means of opening these types of embedded documents. This can be done by opening the parent document and then the embedded document can be opened through this exporter object.

// subdocId is the sequential number of the node in the archive file
Exporter exporterNode = exporter.newArchiveNodeExporter(subdocId);
11.2.2.4 Set the Output Type

In this step, you specify the output format.

exporter.setDestinationFormat(FileFormat.FI_PDF);
11.2.2.5 Provide a Callback Handler

Outside In Technology provides callbacks that allow the developer to intervene at critical points in the export process. To respond to these callbacks, you have to subscribe to any messages that you are interested in by overriding the message handlers from the Callback class. After creating an object of this class, set the callback option to this object and the messages will be passed to your object.

class CallbackHandler extends Callback
{
  … // implementation of messages to handle - described in the API documentation
}
CallbackHandler callback = new CallbackHandler();
exporter.setCallbackHandler(callback);
11.2.2.6 Run the Export

After all the previous steps are completed, you can produce the desired output.

exporter.export();