> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java で FRE for Windows を使用する

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

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

<div id="adding-finereader-engine-library-to-a-java-project">
  ## FineReader Engine ライブラリを Java プロジェクトに追加する
</div>

ABBYY FineReader Engine には、FineReader Engine 用の Java クラスライブラリを含む com.abbyy.FREngine-%BUILD\_ID%.jar ファイルが含まれています。このファイルは [Inc](/ja/fine-reader/engine/distribution/distribution-windows/distribution-kit#incsamples)**Java** フォルダーにあります。このファイルのパスは、コマンドラインの classpath パラメーターや、各種 Java 開発環境のプロジェクト設定で指定できます。例:

```csharp theme={null}
%JDK%\bin\Javac -classpath <path>/com.abbyy.FREngine-%BUILD_ID%.jar Hello.java
```

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

<Warning>
  サポートされている Java Development Kit の一覧については、[System Requirements](/ja/fine-reader/engine/specifications/system-requirements#jdk_requirements) を参照してください。
</Warning>

<div id="loading-and-unloading-finereader-engine">
  ## FineReader Engine の読み込みと解放
</div>

静的な Engine クラスを使用して、[Engine](/ja/fine-reader/engine/api-reference/engine-object-iengine-interface) オブジェクトを読み込むことができます。

Engine クラスには、Engine の読み込みと解放を行う ABBYY FineReader Engine の[関数](/ja/fine-reader/engine/api-reference/functions)に対応するメソッドが用意されています。

| 関数                                                                                               | Engine クラスのメソッド    | Engine クラスのメソッドのシグネチャ                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [InitializeEngine](/ja/fine-reader/engine/api-reference/functions/initializeengine-function)     | InitializeEngine   | `csharp static public IEngine InitializeEngine( String dllFolder, String customerProjectId, String licensePath, String licensePassword, String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception; ` |
| [DeinitializeEngine](/ja/fine-reader/engine/api-reference/functions/deinitializeengine-function) | DeinitializeEngine | `static public void DeinitializeEngine() throws Exception;`                                                                                                                                                                      |

<Accordion title="コード例">
  ```csharp theme={null}
  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;
  ...
  }
  ```
</Accordion>

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

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

<Accordion title="InprocLoader を使用するコード例">
  ```csharp theme={null}
  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();
  ```
</Accordion>

<Accordion title="OutprocLoader を使用するコード例">
  ```csharp theme={null}
  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();
  ```
</Accordion>

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

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

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

<div id="using-engine-in-multi-threaded-java-applications">
  ## マルチスレッドの Java アプリケーションで Engine を使用する
</div>

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

```java theme={null}
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](/ja/fine-reader/engine/api-reference/functions/initializeengine-function) と同じです。 |
| 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](/ja/fine-reader/engine/guided-tour/samples#enginespool) のコードサンプルを参照してください。

<div id="handling-errors">
  ## エラー処理
</div>

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() ) );
    }
}
```

<div id="calling-methods-with-out-parameters">
  ## outパラメーターを持つメソッドの呼び出し
</div>

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

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

次の例では、outパラメーターを [IFRPage::FindPageSplitPosition](/ja/fine-reader/engine/api-reference/document-related-objects/frpage/findpagesplitposition-method) メソッドに参照渡ししています。

<Accordion title="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();
  ```
</Accordion>

次の例では、in/outパラメーターを [ICoordinatesConverter::ConvertCoordinates](/ja/fine-reader/engine/api-reference/image-related-objects/coordinatesconverter/convertcoordinates-method) メソッドに参照渡ししています。

<Accordion title="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();
  ```
</Accordion>

次の例では、配列の outパラメーターを [IPlainText::GetCharacterData](/ja/fine-reader/engine/api-reference/text-related-objects/plaintext/getcharacterdata-method) メソッドに参照渡しする方法を示しています。

<Accordion title="配列の 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[]>();
  ```
</Accordion>

<div id="collecting-garbage">
  ## リソースの解放
</div>

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

<Accordion title="コード例">
  ```csharp theme={null}
  try( IFRDocument document = engine.CreateDocument() )
   {
    // ドキュメントに画像を追加
    document.AddImageFile( imagePath, null, null );
    ...
    // 結果を PDF に保存
    document.Export( pdfExportPath, FileExportFormatEnum.FEF_PDF, pdfParams );
   }
  ```
</Accordion>

HGLOBAL の取り扱い

ABBYY FineReader Engine API の一部のメソッドは、入力パラメーターとしてメモリ ブロックへの HGLOBAL ハンドル ([\_\_int64](/ja/fine-reader/engine/guided-tour/advanced-techniques/programming-aspects/working-with-properties) として渡されます) を受け取ります。HGLOBAL は Windows 固有のため、Java ラッパーでは、これらのメソッドは代わりにメモリ ブロックの内容を `byte[]` として受け取ります。該当するメソッドは次のとおりです。

* [LoadImageDocFromMemory](/ja/fine-reader/engine/api-reference/engine-object-iengine-interface/processing-methods/loadimagedocfrommemory-method) メソッドと [OpenImageFileFromMemory](/ja/fine-reader/engine/api-reference/engine-object-iengine-interface/processing-methods/openimagefilefrommemory-method) メソッド ([Engine](/ja/fine-reader/engine/api-reference/engine-object-iengine-interface) オブジェクト)
* 多くのオブジェクトで提供される [LoadFromMemory](/ja/fine-reader/engine/api-reference/supplementary-objects-and-methods/loadfrommemory-method) メソッド
* [FRDocument](/ja/fine-reader/engine/api-reference/document-related-objects/frdocument) オブジェクトの [AddImageFileFromMemory](/ja/fine-reader/engine/api-reference/document-related-objects/frdocument/addimagefilefrommemory-method) メソッド
* [PDFAttachments](/ja/fine-reader/engine/api-reference/document-related-objects/pdfattachments) オブジェクトの [AddFromMemory](/ja/fine-reader/engine/api-reference/document-related-objects/pdfattachments/addfrommemory-method) メソッド

一方、[Handle](/ja/fine-reader/engine/api-reference/supplementary-objects-and-methods/handle) オブジェクトを返すメソッドは、Java ラッパーでもそのまま返されます。

<div id="working-with-enumerations">
  ## 列挙型の扱い
</div>

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

以下は、[PDFPictureCompressionParams](/ja/fine-reader/engine/api-reference/parameter-objects/export-parameters/pdfpicturecompressionparams) オブジェクトの [BwPictureFormats](/ja/fine-reader/engine/api-reference/parameter-objects/export-parameters/pdfpicturecompressionparams#bwpictureformats) プロパティを設定する方法を示すサンプルコードです。

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

関連項目

[Engine Object のさまざまな読み込み方法](/ja/fine-reader/engine/guided-tour/advanced-techniques/programming-aspects/different-ways-to-load-engine) (Windows 向け)

[Java でのクロスプラットフォーム開発](/ja/fine-reader/engine/guided-tour/advanced-techniques/programming-aspects/cross-platform-development-in-java) (Windows 向け)