English (English)

Using ABBYY FineReader Engine in Java

Because Java is platform-independent, it has no special tools for integration with platform-dependent technologies such as COM. Instead, it provides a truly platform-independent but very low-level interface for integration with any native platform – Java Native Interface (JNI). Creating wrappers using JNI is not an easy task: wrappers need to be written for every interface and method you intend to use, resulting in huge amounts of code. FineReader Engine lets you avoid this problem by providing ready-to-use Java classes for the Engine library. These Java classes can be used directly from Java applications.

If you develop your application on Windows operating system but intend to run it on Linux or Mac OS, you will not need to make any changes in your code but use the .jar file from the distribution package.

The API for the three platforms is the same with some minor exceptions.

Adding FineReader Engine library to a Java project

ABBYY FineReader Engine includes a com.abbyy.FREngine-%BUILD_ID%.jar file, which contains the Java class library for FineReader Engine. You can find it in the Inc\Java folder. The path to this file can be specified in the classpath parameter in the command line and in project settings in different Java development environments. Example:

%JDK%\bin\Javac -classpath <path>/com.abbyy.FREngine-%BUILD_ID%.jar Hello.java

%JDK% is the path to Java Development Kit.

Important! See the list of supported Java Development Kits in System Requirements.

Loading and unloading FineReader Engine

You can use the static Engine class to load the Engine object.

The Engine class provides methods that correspond to the ABBYY FineReader Engine functions for loading and unloading the Engine:

Function Engine class method The signature of the Engine class method
InitializeEngine InitializeEngine 
static public IEngine InitializeEngine( String dllFolder, String customerProjectId,
            String licensePath, String licensePassword,
            String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception;
DeinitializeEngine DeinitializeEngine 
static public void DeinitializeEngine() throws Exception;

Sample code

To load Engine by means of COM, use its GetEngineInprocLoader or GetEngineOutprocLoader methods. See the description of the IEngineLoader interface for details. If you use the GetEngineOutprocLoader method for loading, you do not need to call the IHostProcessControl::SetClientProcessId method as the parent process will be set automatically.

Important! If you develop your application on Windows but intend running it on Linux, do not use these methods for loading Engine. Use only the InitializeEngine method described above. This limitation is due to the fact that objects implementing IEngineLoader are not available on Linux.

Sample code using InprocLoader

Sample code using OutprocLoader

For working with the Engine object created via an engine loader, the Engine class provides the methods which call the corresponding COM functions to marshal the interface pointer across threads:

Method Signature Comment
MarshalInterface 
long MarshalInterface();

Calls the CoMarshalInterface COM function to marshal the IEngine interface. This method should be called on the thread where the engine was created, to ensure that the data needed for creating a proxy object on another thread will be available.

Returns the handle to the marshaling data.
UnmarshalInterface 
IEngine UnmarshalInterface( long handle );

Calls the CoUnmarshalInterface COM function to unmarshal the IEngine interface, i.e., create a proxy object with which the client process will be able to interact in the same way as with the engine itself.

Takes the handle to the marshaling data (returned by the MarshalInterface method) as the input parameter and returns a pointer to the IEngine interface.

Note: The com.abbyy.FREngine-%BUILD_ID%.jar file is a self-unpacking archive which is unpacked on your machine the first time you use FineReader Engine Java API. The default folder where the contents are unpacked is Inc\Java. If you need to use another folder, call the Engine.SetJNIDllFolder method before loading the Engine by any of the methods described above. To find out which folder is currently set for unpacking the archive, call the Engine.GetJNIDllFolder.

Using Engine in multi-threaded Java applications

For multi-threaded Java applications you can use the EnginesPool class, which provides a complete solution for creating and managing a pool of FineReader Engine objects. This class implements the java.lang.Runnable interface.

public class EnginesPool implements Runnable;

Methods of the EnginesPool class are listed below.

Method Signature Comment
constructor 
public EnginesPool( int enginesCount, int waitingEngineTimeout,
            String customerProjectId, String licensePath, String licensePassword,
            String dataFolder, String tempFolder, 
            boolean isSharedCPUCoresMode ) throws Exception;
Creates a new pool of enginesCount Engines. The waitingEngineTimeout sets the timeout for EnginesPool.GetEngine. Other parameters are the same as in InitializeEngine
GetEngine 
public IEngine GetEngine() throws Exception;

Gets an Engine instance from the pool.

Throws an exception if waitingEngineTimeout is exceeded.
ReleaseEngine 
public void ReleaseEngine( IEngine engine,
            boolean isRecycleRequired ) throws Exception;
Returns an Engine instance to the pool. If isRecycleRequired is true, deletes this instance and replaces it with a new one (even if the usage limit is not reached, or automatic recycle is disabled).
SetAutoRecycleUsageCount 
public void SetAutoRecycleUsageCount( int value );
Set how many times a single Engine instance in this pool can be re-used until the instance is recycled: deleted and replaced with a new one automatically. The count can be set to 0 to never recycle automatically (only manual recycling will be possible, via ReleaseEngine). Default is 0 (never recycle automatically).
GetAutoRecycleUsageCount 
public int GetAutoRecycleUsageCount();
Get the Engine instance re-use limit for this pool.
UnloadEngines 
public void UnloadEngines() throws Exception;
Unload all Engines and deinitialize the pool.

See the EnginesPool code sample for an example of using the EnginesPool class.

Handling errors

ABBYY FineReader Engine can throw the exceptions of the following types:

  • java.lang.OutOfMemoryError
  • com.abbyy.FREngine.EngineException

The com.abbyy.FREngine.EngineException exception inherits from the java.lang.Exception and contains one additional method int getHResult, which returns the HRESULT code of the error that occurred. For an exception of this type, you can not only retrieve the error message using the getMessage() method but also retrieve the error code.

try {
    ...
} catch( Exception ex ) {
    displayMessage( "Message = " + ex.getMessage() );
    if( ex instanceof EngineException ) {
        displayMessage( "HResult = " + Integer.toString( ( ( EngineException )ex ).getHResult() ) );
    }
}

Calling methods with out-parameters

There are several methods in ABBYY FineReader Engine API which have out-parameters that receive a new value after the method call and must be passed by reference. These parameters are marked in the type library and in descriptions of methods in this Developer's Help as [out] or [in, out].

When working with ABBYY FineReader Engine in Java, you have to use a special Ref class to pass a parameter by reference. See examples below.

Example in which the out-parameters are passed by reference to the IFRPage::FindPageSplitPosition method:

Sample code for out-parameters

Example in which the in/out parameters are passed by reference to the ICoordinatesConverter::ConvertCoordinates method:

Sample code for in/out parameters

Example in which the array out-parameters are passed by reference to the IPlainText::GetCharacterData method:

Sample code for array out-parameters

Collecting garbage

ABBYY FineReader Engine supports working with the AutoCloseable interface, which allows you to use the try statement to access the resources allocated for objects. It means that once the try block reaches the end, all allocated resources will be closed automatically, without explicitly calling closure methods. We recommend that you use the try statement for all objects in your code (see the example below):

Sample code

Working with HGLOBAL

Some of the methods in ABBYY FineReader Engine API take as an input parameter an HGLOBAL handle to a memory block (passed as __int64). As HGLOBAL is a Windows-specific entity, in Java wrapper these methods receive instead the contents of the memory block as byte[]. See the list of these methods:

On the other hand, the methods which return a Handle object return it in Java wrapper as well.

Working with enumerations

Methods and properties which accept a combination of enumeration constants require the int value to be passed to the method/property. To obtain the int value of an enumeration constant, use the getValue method which is supported by all enumerations.

Here is sample code showing how to set the BwPictureFormats property of the PDFPictureCompressionParams object:

IPDFExportParams pep = engine.CreatePDFExportParams();
IPDFPictureCompressionParams ppcp = pep.getPictureCompressionParams();
ppcp.setBwPictureFormats(BwPictureFormatsEnum.BWPF_Auto.getValue());

See also

Different Ways to Load the Engine Object

Cross-platform development in Java

24.03.2023 8:51:52

Usage of Cookies. In order to optimize the website functionality and improve your online experience ABBYY uses cookies. You agree to the usage of cookies when you continue using this site. Further details can be found in our Privacy Notice.