BCL easyConverter SDK
easyConverter SDK Usermanual
PDF-to-Word Programming API  |  Download Free Trial  |  Contact Us to Purchase

Native Java API

In addition to the JACOB (Java COM) API, easyConverter SDK is also available as a native Java API. The API layer is written in 100% Java code. It does not rely on any COM objects or Java-Native Interface (JNI).

Rationale

The native Java API works by launching an external worker process (also known as a sandbox), which is not a Java application, but rather native x86 machine code. However, this external process is completely isolated. Named pipes are used for communication in between the 100% Java world and the x86 sandbox.

There are numerous advantages to using this new native Java API, instead of the older JACOB version:

There are no known disadvantages to using the native Java API versus the JACOB API.

Usage

The native Java API is very similar to the JACOB API, with only a few distinct differences.

First, you need to import com.bcl.easyconverter.word.*;.

The jar file is called easyConverterWord.jar, which is under c:\Program Files\BCL Technologies\easyConverter SDK 5\Common\.

Oracle JAVA SE Development Kit 1.5 or above is required.

COM exceptions were replaced by the new PDF2WordException.

The PDF2Word class has a dispose() method, which means it really needs to be deterministically disposed. Relying on the garbage collector is not recommended, because each PDF2Word object launches a separate worker process. Even though these worker processes are sleeping while not executing a function, they are still in the memory, and only really quit when the PDF2Word object is disposed.

The PDF2Word object should be treated as if it were an expensive resource, such as a file, mutex, or a database connection. If you would like to know what really is inside PDF2Word, it is just a named pipe. However, the worker process is programmed to only quit when the pipe is closed.

If the customer's application crashes, the system automatically closes all pipes belonging to the process, which means all related worker processes automatically quit as well.

The minimal Java sample code looks like this:
(Note: all Native Java sample code and declarations have a light red background color)

PDF2Word pdf2word = new PDF2Word();
try
{
   pdf2word.ConvertToWord("c:\\temp\\input.pdf", "c:\\temp\\output.doc");
}
catch(PDF2WordException e)
{
   System.out.println(e);
}
finally
{
   pdf2word.dispose();
}

The key here is the finally block, which calls dispose().

PDF2Word's constructor is designed to never throw exceptions. That's because it does not launch a worker process and does not create a named pipe, it merely initializes a few variables to their default values. In other words, creating a PDF2Word object is extremely lightweight, like creating a Color object.

However, as soon as you do anything else, even getting a property, it instantly launches a worker process.

Notification Events

Notification events are new to the Java API, as they did not exist in JACOB. Here is an example that catches OnPageStart, which is called before converting each page:

SampleEvents handler = new SampleEvents();
PDF2Word pdf2word = new PDF2Word();
try
{
   pdf2word.events = handler;
   pdf2word.ConvertToWord("c:\\temp\\input.pdf", "c:\\temp\\output.doc");
}
catch(PDF2WordException e)
{
   System.out.println(e);
}
finally
{
   pdf2word.dispose();
}

SampleEvents is your class, where you have a chance to respond to all events:

import com.bcl.easypdf.converter.*;

public class SampleEvents implements IPDF2HTMLMonitorEvents
{
        public cnvResponse OnPageStartEventHandler(int PageNumber, int PageCount, String FileName)
        {
                System.out.print("Page ");
                System.out.print(pageNumber);
                System.out.print("...");
                return cnvResponse.CNV_CONTINUE;
        }

        public void OnConversionFinishedEventHandler(int ErrCode)
        {
        }
}

Note that even if you just want to handle a single event, you are still required to handle them all at once.

Loader

PDF2Word does not require easyConverter Loader, so it is not used by default. However, some users might want to force the use of Loader. This is mainly done in order to gain permission to special directories.

Forcing Loader is very simple, but it needs to be done as first thing, immediately after the PDF2Word object is created:

PDF2Word pdf2word = new PDF2Word();
pdf2word.useLoader = true; // use Loader
try
{
   pdf2word.ConvertToWord("c:\\temp\\input.pdf", "c:\\temp\\output.doc");
}
catch(PDF2WordException e)
{
   System.out.println(e);
}
finally
{
   pdf2word.dispose();
}

If you do anything at all with the PDF2Word object, changing useLoader has no effect whatsoever anymore. That also means you can't change useLoader in the middle. useLoader should be treated as if it were part of the constructor.

In Java, PDF2Word cannot automatically start the Loader service. Therefore it is imperative that you change the Loader settings from Manual to Automatic and make sure it's running.

If Loader is requested but not running, PDF2Word will fail with an exception.

Loader is a BCL-provided service that requires special setup.