在 Windows 上搭配 Java 使用 FRE

本主題適用於 Windows 版 FRE。

將 FineReader Engine 程式庫新增至 Java 專案

ABBYY FineReader Engine 包含 com.abbyy.FREngine-%BUILD_ID%.jar 檔案，其中內含 FineReader Engine 的 Java 類別程式庫。您可以在 Inc\Java 資料夾中找到此檔案。您可以在命令列的 classpath 參數中，以及各種 Java 開發環境的專案設定中，指定此檔案的路徑。範例：

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

%JDK% 是 Java Development Kit 的路徑。

請參閱系統需求中的支援 Java Development Kit 清單。

載入與解除載入 FineReader Engine

您可以使用靜態 Engine 類別來載入 Engine 物件。 Engine 類別提供的方法，對應於 ABBYY FineReader Engine 用來載入及解除載入 Engine 的 functions：

函式	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 方法。這項限制是因為 Linux 不提供實作 IEngineLoader 的物件。

使用 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 物件，Engine 類別提供了會呼叫對應 COM 函式的方法，以便在線程之間封送介面指標：

方法	簽章	註解
MarshalInterface	`long MarshalInterface();`	呼叫 CoMarshalInterface COM 函式來封送 IEngine 介面。此方法應在建立 Engine 的執行緒上呼叫，以確保在另一個執行緒上建立代理物件所需的資料可供使用。回傳封送資料的 Handle。
UnmarshalInterface	`csharp IEngine UnmarshalInterface( long handle );`	呼叫 CoUnmarshalInterface COM 函式來還原封送的 IEngine 介面，也就是建立一個代理物件，讓用戶端程序能夠像與 Engine 本身互動一樣進行操作。此方法會將封送資料的 Handle (由 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 );`	設定此集區中單一 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，此方法會回傳所發生錯誤的 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 Handle 作為輸入參數 (以 __int64 傳遞) 。由於 HGLOBAL 是 Windows 特有的類型，因此在 Java wrapper 中，這些方法會改為接收記憶體區塊內容的 byte[]。請參閱下列方法清單：

LoadImageDocFromMemory、OpenImageFileFromMemory 方法，屬於 Engine 物件
LoadFromMemory 方法，由許多物件提供
AddImageFileFromMemory 方法，屬於 FRDocument 物件
AddFromMemory 方法，屬於 PDFAttachments 物件

另一方面，會傳回 Handle 物件的方法，在 Java wrapper 中也同樣會傳回該物件。

使用列舉

接受列舉常數組合的方法和屬性，必須將 int 值傳遞至方法/屬性。若要取得列舉常數的 int 值，請使用所有列舉皆支援的 getValue 方法。以下範例程式碼示範如何設定 PDFPictureCompressionParams 物件的 BwPictureFormats 屬性：

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

另請參閱載入 Engine 物件的不同方式 (Windows) Java 跨平台開發 (Windows)

總覽

基本使用案例實作

進階技巧

在 Windows 上搭配 Java 使用 FRE

將 FineReader Engine 程式庫新增至 Java 專案

載入與解除載入 FineReader Engine

在多執行緒 Java 應用程式中使用 Engine

處理錯誤

使用 out 參數呼叫方法

垃圾回收

使用列舉

總覽

基本使用案例實作

進階技巧

​將 FineReader Engine 程式庫新增至 Java 專案

​載入與解除載入 FineReader Engine

​在多執行緒 Java 應用程式中使用 Engine

​處理錯誤

​使用 out 參數呼叫方法

​垃圾回收

​使用列舉

將 FineReader Engine 程式庫新增至 Java 專案

載入與解除載入 FineReader Engine

在多執行緒 Java 應用程式中使用 Engine

處理錯誤

使用 out 參數呼叫方法

垃圾回收

使用列舉