Java で FRE for Windows を使用する

Windows で Java から ABBYY FineReader Engine を使用するには、Inc/Java フォルダー内の com.abbyy.FREngine.jar を classpath に追加し、Engine をロードおよびアンロードします。

このトピックは FRE for Windows を対象としています。

​

FineReader Engine ライブラリを Java プロジェクトに追加する

ABBYY FineReader Engine には、FineReader Engine 用の Java クラスライブラリを含む com.abbyy.FREngine-%BUILD_ID%.jar ファイルが含まれています。このファイルは IncJava フォルダーにあります。このファイルのパスは、コマンドラインの classpath パラメーターや、各種 Java 開発環境のプロジェクト設定で指定できます。例:

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

%JDK% は Java Development Kit のパスです。

サポートされている Java Development Kit の一覧については、System Requirements を参照してください。

​

FineReader Engine の読み込みと解放

静的な Engine クラスを使用して、Engine オブジェクトを読み込むことができます。

Engine クラスには、Engine の読み込みと解放を行う ABBYY FineReader Engine の関数に対応するメソッドが用意されています。

関数	Engine クラスのメソッド	Engine クラスのメソッドのシグネチャ
InitializeEngine	InitializeEngine	csharp 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;

コード例

import com.abbyy.FREngine.*;
public class Hello {
    public static void main( String[] args )
    {
        try {
            // オンライン ライセンスで Engine を読み込む
            engine = Engine.InitializeEngine( dllPath, customerProjectId, LicensePath, LicensePassword, "", "", false );
            try {
                // 定義済みプロファイルを読み込む
                engine.LoadPredefinedProfile( "DocumentConversion_Accuracy" );
                // 画像を処理する
                IFRDocument document = engine.CreateFRDocument();
                ...
            } finally {
                engine = null;
                System.runFinalization();
                Engine.DeinitializeEngine();
            }
        } catch( Exception ex ) {
            trace( ex.getMessage() );
        }
    }
    private IEngine engine = null;
...
}

COM を使用して Engine を読み込むには、GetEngineInprocLoader または GetEngineOutprocLoader メソッドを使用します。詳細については、IEngineLoader インターフェイスの説明を参照してください。読み込みに GetEngineOutprocLoader メソッドを使用する場合、親プロセスは自動的に設定されるため、IHostProcessControl::SetClientProcessId メソッドを呼び出す必要はありません。

アプリケーションを Windows 上で開発し、Linux 上で実行する予定がある場合は、Engine の読み込みにこれらのメソッドを使用しないでください。上記で説明した InitializeEngine メソッドのみを使用してください。この制限は、IEngineLoader を実装するオブジェクトを Linux では使用できないためです。

InprocLoader を使用するコード例

import com.abbyy.FREngine.*;
// オンライン ライセンスで Engine を読み込む
engineLoader = Engine.GetEngineInprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Engine を解放する
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

OutprocLoader を使用するコード例

import com.abbyy.FREngine.*;
// オンライン ライセンスで Engine を読み込む
engineLoader = Engine.GetEngineOutprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Engine を解放する
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

Engine ローダー経由で作成された Engine object を操作するために、Engine クラスには、対応する COM 関数を呼び出してスレッド間で インターフェイス pointer をマーシャリングするメソッドが用意されています。

メソッド	シグネチャ	コメント
MarshalInterface	long MarshalInterface();	CoMarshalInterface COM 関数を呼び出して、IEngine インターフェイスをマーシャリングします。このメソッドは、別のスレッドでプロキシ オブジェクトを作成するために必要なデータを利用可能にするため、engine が作成されたスレッドで呼び出す必要があります。マーシャリング データへのハンドルを返します。
UnmarshalInterface	csharp IEngine UnmarshalInterface( long handle );	CoUnmarshalInterface COM 関数を呼び出して、IEngine インターフェイスのマーシャリングを解除します。つまり、client process が engine 自体と同じようにやり取りできるプロキシ オブジェクトを作成します。入力パラメーターとしてマーシャリング データへのハンドル (MarshalInterface メソッドが返す値) を受け取り、IEngine インターフェイスへのポインターを返します。

com.abbyy.FREngine-%BUILD_ID%.jar ファイルは自己展開型アーカイブで、FineReader Engine Java API を初めて使用する際に、お使いのマシン上で展開されます。内容の展開先となる既定のフォルダーは、Windows では Inc\Java です。別のフォルダーを使用する必要がある場合は、上記で説明したいずれかの方法で Engine をロードする前に、Engine.SetJNIDllFolder メソッドを呼び出してください。現在アーカイブの展開先として設定されているフォルダーを確認するには、Engine.GetJNIDllFolder を呼び出してください。

​

マルチスレッドの Java アプリケーションで Engine を使用する

マルチスレッドの Java アプリケーションでは、EnginesPool クラスを使用できます。このクラスは、FineReader Engine オブジェクトのプールを作成および管理するための包括的なソリューションを提供します。java.lang.Runnable インターフェイスを実装しています。

public class EnginesPool implements Runnable;

EnginesPool クラスのメソッドを以下に示します。

メソッド	シグネチャ	コメント
constructor	public EnginesPool( int enginesCount, int waitingEngineTimeout, String customerProjectId, String licensePath, String licensePassword, String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception;	enginesCount 個の Engine で構成される新しいプールを作成します。waitingEngineTimeout は EnginesPool.GetEngine のタイムアウトを設定します。その他のパラメーターは InitializeEngine と同じです。
GetEngine	csharp public IEngine GetEngine() throws Exception;	プールから Engine インスタンスを取得します。waitingEngineTimeout を超えると例外をスローします。
ReleaseEngine	csharp public void ReleaseEngine( IEngine engine, boolean isRecycleRequired ) throws Exception;	Engine インスタンスをプールに戻します。isRecycleRequired が true の場合、このインスタンスを削除し、新しいインスタンスに置き換えます (使用回数の上限に達していない場合や、自動リサイクルが無効な場合でも) 。
SetAutoRecycleUsageCount	public void SetAutoRecycleUsageCount( int value );	このプール内の 1 つの Engine インスタンスを、リサイクル (削除して新しいインスタンスに置き換え) されるまでに何回再利用できるかを設定します。自動リサイクルを無効にするには、回数を 0 に設定します (この場合、ReleaseEngine による手動リサイクルのみ可能です) 。既定値は 0 です (自動リサイクルなし) 。
GetAutoRecycleUsageCount	public int GetAutoRecycleUsageCount();	このプールにおける Engine インスタンスの再利用回数の上限を取得します。
UnloadEngines	public void UnloadEngines() throws Exception;	すべての Engine をアンロードし、プールを終了します。

EnginesPool クラスの使用例については、EnginesPool のコードサンプルを参照してください。

​

エラー処理

ABBYY FineReader Engine では、次の型の例外がスローされることがあります。

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

com.abbyy.FREngine.EngineException 例外は java.lang.Exception を継承しており、追加のメソッド int getHResult を 1 つ持っています。このメソッドは、発生したエラーの HRESULT コードを返します。この型の例外では、getMessage() メソッドを使用してエラーメッセージを取得できるだけでなく、エラーコードも取得できます。

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

​

outパラメーターを持つメソッドの呼び出し

ABBYY FineReader Engine API には、メソッドの呼び出し後に新しい値を受け取り、参照渡しで渡す必要がある outパラメーターを持つメソッドがいくつかあります。これらのパラメーターは、型ライブラリおよびこの開発者向けヘルプのメソッド説明で [out] または [in, out] として示されています。

Java で ABBYY FineReader Engine を使用する場合、パラメーターを参照渡しするには、専用の Ref クラスを使用する必要があります。以下の例を参照してください。

次の例では、outパラメーターを IFRPage::FindPageSplitPosition メソッドに参照渡ししています。

outパラメーターのコード例

Ref<PageSplitDirectionEnum> _ps = new Ref<PageSplitDirectionEnum>();
Ref<Integer> _start = new Ref<Integer>();
Ref<Integer> _end = new Ref<Integer>();
page.FindPageSplitPosition( null, null, _ps, _start, _end );
PageSplitDirectionEnum ps = _ps.get();
Integer start = _start.get();
Integer end = _end.get();

次の例では、in/outパラメーターを ICoordinatesConverter::ConvertCoordinates メソッドに参照渡ししています。

in/outパラメーターのコード例

Ref<Integer> _x = new Ref<Integer>( 100 );
Ref<Integer> _y = new Ref<Integer>( 200 );
cnv.ConvertCoordinates( ImageTypeEnum.IT_Modified, ImageTypeEnum.IT_Base, _x, _y );
Integer x = _x.get();
Integer y = _y.get();

次の例では、配列の outパラメーターを IPlainText::GetCharacterData メソッドに参照渡しする方法を示しています。

配列の outパラメーターのコード例

Ref<int[]> _leftBorders = new Ref<int[]>();
Ref<int[]> _topBorders = new Ref<int[]>();
Ref<int[]> _rightBorders = new Ref<int[]>();
Ref<int[]> _bottomBorders = new Ref<int[]>();
Ref<int[]> _confidences = new Ref<int[]>();
Ref<boolean[]> _isSuspicious = new Ref<boolean[]>();
plainText.GetCharacterData( _pageNumbers, _leftBorders, _topBorders, _rightBorders, _bottomBorders, _confidences, _isSuspicious );
int[] pageNumbers = _pageNumbers.get();
int[] leftBorders = _leftBorders.get();
int[] topBorders = _topBorders.get();
int[] rightBorders = _rightBorders.get();
int[] bottomBorders = _bottomBorders.get();
int[] confidences = _confidences.get();
boolean[]isSuspicious = _isSuspicious.get();
Ref<int[]> _pageNumbers = new Ref<int[]>();

​

リソースの解放

FineReader Engine は AutoCloseable インターフェイスに対応しており、try 文を使用してオブジェクトに割り当てられたリソースを扱うことができます。これにより、try ブロックを抜けると、クローズ用のメソッドを明示的に呼び出さなくても、割り当てられたすべてのリソースが自動的に閉じられます。コード内のすべてのオブジェクトで try 文を使用することをお勧めします (以下の例を参照) 。

コード例

try( IFRDocument document = engine.CreateDocument() )
 {
  // ドキュメントに画像を追加
  document.AddImageFile( imagePath, null, null );
  ...
  // 結果を PDF に保存
  document.Export( pdfExportPath, FileExportFormatEnum.FEF_PDF, pdfParams );
 }

HGLOBAL の取り扱い

ABBYY FineReader Engine API の一部のメソッドは、入力パラメーターとしてメモリ ブロックへの HGLOBAL ハンドル (__int64 として渡されます) を受け取ります。HGLOBAL は Windows 固有のため、Java ラッパーでは、これらのメソッドは代わりにメモリ ブロックの内容を byte[] として受け取ります。該当するメソッドは次のとおりです。

• LoadImageDocFromMemory メソッドと OpenImageFileFromMemory メソッド (Engine オブジェクト)
• 多くのオブジェクトで提供される LoadFromMemory メソッド
• FRDocument オブジェクトの AddImageFileFromMemory メソッド
• PDFAttachments オブジェクトの AddFromMemory メソッド

一方、Handle オブジェクトを返すメソッドは、Java ラッパーでもそのまま返されます。

​

列挙型の扱い

列挙定数の組み合わせを受け取るメソッドおよびプロパティでは、int 値をメソッドまたはプロパティに渡す必要があります。列挙定数の int 値を取得するには、すべての列挙型でサポートされている getValue メソッドを使用します。

以下は、PDFPictureCompressionParams オブジェクトの BwPictureFormats プロパティを設定する方法を示すサンプルコードです。

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

関連項目

Engine Object のさまざまな読み込み方法 (Windows 向け)

Java でのクロスプラットフォーム開発 (Windows 向け)