在 Java 中使用 ABBYY FineReader Engine
Java 独立于平台，没有特殊工具用于和 COM 这种依靠平台的技术进行集成。相反，Java 提供了一个真正独立于平台但级别较低的接口用于和任何本地平台集成 – Java 本地接口 (JNI)。用 JNI 创建包装器并不简单：必须为打算使用的每个接口和方法写入包装器，这会产生大量代码。FineReader Engine 通过提供适合 Engine 库的即时可用 Java 类别避免上述问题。您可直接从 Java 应用程序中使用这些 Java 类别。
如果您在 Windows 操作系统上开发应用程序但打算在 Linux 或 Mac OS 上运行，无需对代码进行任何更改，使用来自分发包的 .jar 文件即可。
除个别例外情况外，三个平台的 API 是相同的。
添加 FineReader Engine 库到 Java 项目
ABBYY FineReader Engine 包括一个 com.abbyy.FREngine-%BUILD_ID%.jar 文件，其包含适合带有 Java 类别库的 FineReader Engine。您可以在 Inc\Java 文件夹中找到它。在不同的 Java 开发环境中，该文件的路径可以在命令行和项目设置中的 classpath 参数中指定。示例：
%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：
| 函数 | Engine 类别方法 | Engine 类别方法的签名 |
|---|---|---|
| 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; |
示例代码
要通过 COM 加载 Engine，请使用其 GetEngineInprocLoader 或 GetEngineOutprocLoader 方法。请参见 IEngineLoader 接口说明了解详情。如果使用 GetEngineOutprocLoader 方法进行加载，则不需要调用 IHostProcessControl::SetClientProcessId 方法，因为会自动设置父级进程
重要事项！ 如果在 Windows 上开发应用程序却打算在 Linux 上运行，请勿使用这些方法加载 Engine。仅上述 InitializeEngine 方法适用。原因在于实施 IEngineLoader 的对象在 Linux 上不可用。
使用 InprocLoader 的示例代码
使用 OutprocLoader 的示例代码
对于处理用引擎加载器创建的 Engine 对象，Engine 类别提供的方法可调用相应的 COM 函数来封送各线程的接口指针：
| 方法 | 签名 | 注释 |
|---|---|---|
| MarshalInterface |
long MarshalInterface();
|
调用 CoMarshalInterface COM 函数来封送 IEngine 接口。该方法应该在创建引擎的线程上调用，以确保在另一个线程上创建代理对象所需的数据可用。 将句柄返回到封送数据。 |
| UnmarshalInterface |
IEngine UnmarshalInterface( long handle );
|
调用 CoUnmarshalInterface COM 函数解除封送 IEngine 接口，即创建一个代理对象，客户端进程可以用它就像和引擎本身交互一样进行交互。 将句柄作为输入参数采用到封送数据（由 MarshalInterface 方法返回），并将指针返回到 IEngine 接口。 |
注： com.abbyy.FREngine-%BUILD_ID%.jar 文件是自解压缩存档，您第一次使用 FineReader Engine Java API 时会在您的机器上进行解压缩。内容解压缩的默认文件夹为 Inc\Java。如果使用另一个文件夹，请在加载 Engine 之前用上述任何方法调用 Engine.SetJNIDllFolder 方法。如需查找当前的解压缩存档文件夹，请调用 Engine.GetJNIDllFolder。
在多线程 Java 应用程序中使用 Engine
对于多线程 Java 应用程序，您可以使用 EnginesPool 类别，它可提供创建和管理 FineReader Engine 对象池的完整解决方案。该类别实施 java.lang.Runnable 接口。
public class EnginesPool implements Runnable;
EnginesPool 类别方法列举如下。
| 方法 | 签名 | 注释 |
|---|---|---|
| 构造函数 |
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 |
public IEngine GetEngine() throws Exception;
|
从池获取 Engine 实例。 如果超出 waitingEngineTimeout 则引发异常。 |
| ReleaseEngine |
public void ReleaseEngine( IEngine engine, boolean isRecycleRequired ) throws Exception; |
返回 Engine 实例到池。如果 isRecycleRequired 为真，则删除该实例，将其替换为新实例（即使未达到使用限制，或者自动回收已被禁用）。 |
| SetAutoRecycleUsageCount |
public void SetAutoRecycleUsageCount( int value ); |
设置该池中的单个 Engine 实例可以重新使用多少次直到实例被回收：自动删除并代之以新的。计数可以设为 0 从而绝不自动回收（只能通过 ReleaseEngine 手动回收）。默认为 0 （绝不允许自动回收）。 |
| GetAutoRecycleUsageCount |
public int GetAutoRecycleUsageCount(); |
获取该池的 Engine 实例重新使用限制。 |
| UnloadEngines |
public void UnloadEngines() throws Exception; |
卸载所有 Engines 并取消初始化池。 |
另请参见 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() ) ); } }
调用有外参数的方法
ABBYY FineReader Engine API 中有几种方法有外参数，它们在方法调用后会收到新值，必须以引用方式传递。这些参数在类型库和本“Developer's Help”的方法说明中被标记为 [out] or [in, out]。
当在 Java 中使用 ABBYY FineReader Engine 时，您必须使用特殊的 Ref 类别来通过引用传递参数。请参见以下示例。
外参数以引用方式传递到 IFRPage::FindPageSplitPosition 方法的示例：
外参数的示例代码
输入/输出参数被引用传递到 ICoordinatesConverter::ConvertCoordinates 方法的示例：
输入/输出参数的示例代码
阵列外参数以引用方式传递到 IPlainText::GetCharacterData 方法的示例：
阵列外参数的范例代码
收集垃圾
ABBYY FineReader Engine 支持处理 AutoCloseable 接口，您可使用 try 语句访问分配给对象的资源。这说明一旦 try 块达到末尾，所有被分配的资源将被自动关闭，不会明确调用关闭方法。建议为代码中的所有对象使用 try 语句（请参见以下示例）：
示例代码
处理 HGLOBAL
ABBYY FineReader Engine API 中的一些方法将 HGLOBAL 句柄作为输入参数带到内存块（传递为 __int64）。由于 HGLOBAL 是针对 Windows 的实体，在 Java 包装中这些方法收到的内存块内容是 byte[]。另请参阅这些方法列表：
- Engine 对象的 LoadImageDocFromMemory 和 OpenImageFileFromMemory 方法
- 这些对象提供的 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());
另请参阅
9/17/2024 3:14:41 PM