Uso de Java con FRE for Windows

Este tema se aplica a FRE for Windows.

Agregar la biblioteca de FineReader Engine a un proyecto Java

ABBYY FineReader Engine incluye un archivo com.abbyy.FREngine-%BUILD_ID%.jar, que contiene la biblioteca de clases de Java para FineReader Engine. Puede encontrarlo en la carpeta IncJava. La ruta de acceso a este archivo se puede especificar en el parámetro classpath de la línea de comandos y en la configuración del proyecto en distintos entornos de desarrollo de Java. Ejemplo:

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

%JDK% es la ruta de acceso al Java Development Kit.

Consulte la lista de Java Development Kits compatibles en Requisitos del sistema.

Carga y descarga de FineReader Engine

Puede usar la clase estática Engine para cargar el objeto Engine. La clase Engine proporciona métodos que corresponden a las funciones de ABBYY FineReader Engine para cargar y descargar el Engine:

Función	Método de la clase Engine	Firma del método de la clase 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;`

Código de ejemplo

import com.abbyy.FREngine.*;
public class Hello {
    public static void main( String[] args )
    {
        try {
            // Cargar el Engine con licencia en línea
            engine = Engine.InitializeEngine( dllPath, customerProjectId, LicensePath, LicensePassword, "", "", false );
            try {
                // Cargar un perfil predefinido
                engine.LoadPredefinedProfile( "DocumentConversion_Accuracy" );
                // Procesar imágenes
                IFRDocument document = engine.CreateFRDocument();
                ...
            } finally {
                engine = null;
                System.runFinalization();
                Engine.DeinitializeEngine();
            }
        } catch( Exception ex ) {
            trace( ex.getMessage() );
        }
    }
    private IEngine engine = null;
...
}

Para cargar Engine mediante COM, use sus métodos GetEngineInprocLoader o GetEngineOutprocLoader. Consulte la descripción de la interfaz IEngineLoader para obtener más información. Si usa el método GetEngineOutprocLoader para la carga, no necesita llamar al método IHostProcessControl::SetClientProcessId, ya que el proceso padre se establecerá automáticamente.

Si desarrolla su aplicación en Windows pero tiene previsto ejecutarla en Linux, no use estos métodos para cargar Engine. Use solo el método InitializeEngine descrito anteriormente. Esta limitación se debe a que los objetos que implementan IEngineLoader no están disponibles en Linux.

Código de ejemplo con InprocLoader

import com.abbyy.FREngine.*;
// Cargar el Engine con licencia en línea
engineLoader = Engine.GetEngineInprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Descargar el Engine
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

Código de ejemplo con OutprocLoader

import com.abbyy.FREngine.*;
// Cargar el Engine con licencia en línea
engineLoader = Engine.GetEngineOutprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Descargar el Engine
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

Para trabajar con el objeto Engine creado mediante un cargador de Engine, la clase Engine proporciona métodos que llaman a las funciones COM correspondientes para serializar el puntero de interfaz entre hilos:

Método	Firma	Comentario
MarshalInterface	`long MarshalInterface();`	Llama a la función COM CoMarshalInterface para serializar la interfaz IEngine. Este método debe llamarse en el hilo donde se creó el Engine, para garantizar que estén disponibles los datos necesarios para crear un objeto proxy en otro hilo. Devuelve el handle de los datos de serialización.
UnmarshalInterface	`csharp IEngine UnmarshalInterface( long handle );`	Llama a la función COM CoUnmarshalInterface para deserializar la interfaz IEngine, es decir, crear un objeto proxy con el que el proceso cliente podrá interactuar del mismo modo que con el propio Engine. Toma el handle de los datos de serialización (devuelto por el método MarshalInterface) como parámetro de entrada y devuelve un puntero de interfaz a IEngine.

El archivo com.abbyy.FREngine-%BUILD_ID%.jar es un archivo autoextraíble que se descomprime en su equipo la primera vez que usa la API de Java de FineReader Engine. La carpeta predeterminada donde se extrae el contenido es Inc\Java para Windows. Si necesita usar otra carpeta, llame al método Engine.SetJNIDllFolder antes de cargar el componente Engine mediante cualquiera de los métodos descritos anteriormente. Para saber qué carpeta está configurada actualmente para extraer el archivo, llame a Engine.GetJNIDllFolder.

Uso de Engine en aplicaciones Java multihilo

Para las aplicaciones Java multihilo, puede usar la clase EnginesPool, que proporciona una solución completa para crear y administrar un pool de objetos de FineReader Engine. Esta clase implementa la interfaz java.lang.Runnable.

public class EnginesPool implements Runnable;

A continuación se enumeran los métodos de la clase EnginesPool.

Método	Firma	Comentario
constructor	`public EnginesPool( int enginesCount, int waitingEngineTimeout, String customerProjectId, String licensePath, String licensePassword, String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception;`	Crea un nuevo pool de `enginesCount` Engines. `waitingEngineTimeout` establece el tiempo de espera de `EnginesPool.GetEngine`. Los demás parámetros son los mismos que en InitializeEngine
GetEngine	`csharp public IEngine GetEngine() throws Exception;`	Obtiene una instancia de Engine del pool. Genera una excepción si se supera `waitingEngineTimeout`.
ReleaseEngine	`csharp public void ReleaseEngine( IEngine engine, boolean isRecycleRequired ) throws Exception;`	Devuelve una instancia de Engine al pool. Si `isRecycleRequired` es true, elimina esta instancia y la sustituye por una nueva (incluso si no se ha alcanzado el límite de uso o si el reciclaje automático está deshabilitado).
SetAutoRecycleUsageCount	`public void SetAutoRecycleUsageCount( int value );`	Establece cuántas veces puede reutilizarse una misma instancia de Engine en este pool antes de reciclarse, es decir, de eliminarse y sustituirse automáticamente por una nueva. El valor puede establecerse en 0 para no reciclarla nunca automáticamente (solo será posible el reciclaje manual mediante `ReleaseEngine`). El valor predeterminado es 0 (sin reciclaje automático).
GetAutoRecycleUsageCount	`public int GetAutoRecycleUsageCount();`	Obtiene el límite de reutilización de una instancia de Engine para este pool.
UnloadEngines	`public void UnloadEngines() throws Exception;`	Descarga todos los Engines y desinicializa el pool.

Consulte el sample de código de EnginesPool para ver un ejemplo de uso de la clase EnginesPool.

Manejo de errores

ABBYY FineReader Engine puede lanzar excepciones de los siguientes tipos:

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

La excepción com.abbyy.FREngine.EngineException hereda de java.lang.Exception y contiene un método adicional, int getHResult, que devuelve el código HRESULT del error producido. Para una excepción de este tipo, no solo puede obtener el mensaje de error mediante el método getMessage(), sino también el código de error.

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

Llamada a métodos con parámetros de salida

Hay varios métodos en la API de ABBYY FineReader Engine que tienen parámetros de salida que reciben un nuevo valor después de la llamada al método y deben pasarse por referencia. Estos parámetros están marcados en la biblioteca de tipos y en las descripciones de los métodos de esta ayuda para desarrolladores como [out] o [in, out]. Al trabajar con ABBYY FineReader Engine en Java, debe usar una clase Ref especial para pasar un parámetro por referencia. Consulte los ejemplos a continuación. Ejemplo en el que los parámetros de salida se pasan por referencia al método IFRPage::FindPageSplitPosition:

Código de ejemplo para parámetros de salida

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

Ejemplo en el que los parámetros de entrada/salida se pasan por referencia al método ICoordinatesConverter::ConvertCoordinates:

Código de ejemplo para parámetros de entrada/salida

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

El siguiente ejemplo muestra los parámetros de salida de tipo array pasados por referencia al método IPlainText::GetCharacterData:

Código de ejemplo para parámetros de salida de tipo array

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[]>();

Recolección de basura

FineReader Engine es compatible con la interfaz AutoCloseable, que le permite usar la instrucción try para gestionar los recursos asignados a los objetos. Esto significa que, una vez que el bloque try llega a su fin, todos los recursos asignados se cerrarán automáticamente, sin necesidad de llamar explícitamente a métodos de cierre. Le recomendamos que use la instrucción try para todos los objetos de su código (consulte el ejemplo siguiente):

Código de ejemplo

try( IFRDocument document = engine.CreateDocument() )
 {
  // Agregar imagen a un documento
  document.AddImageFile( imagePath, null, null );
  ...
  // Guardar resultados en PDF
  document.Export( pdfExportPath, FileExportFormatEnum.FEF_PDF, pdfParams );
 }

Uso de HGLOBAL Algunos de los métodos de la API de ABBYY FineReader Engine reciben como parámetro de entrada un handle HGLOBAL a un bloque de memoria (pasado como __int64). Como HGLOBAL es una entidad específica de Windows, en el wrapper de Java estos métodos reciben, en su lugar, el contenido del bloque de memoria como byte[]. Consulte la lista de estos métodos:

Métodos LoadImageDocFromMemory y OpenImageFileFromMemory del objeto Engine
Método LoadFromMemory disponible en muchos objetos
Método AddImageFileFromMemory del objeto FRDocument
Método AddFromMemory del objeto PDFAttachments

Por otro lado, los métodos que devuelven un objeto Handle también lo devuelven en el wrapper de Java.

Trabajar con enumeraciones

Los métodos y las propiedades que aceptan una combinación de constantes de enumeración requieren que se pase al método o a la propiedad el valor int. Para obtener el valor int de una constante de enumeración, use el método getValue, compatible con todas las enumeraciones. A continuación se muestra un código de ejemplo de cómo establecer la propiedad BwPictureFormats del objeto PDFPictureCompressionParams:

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

Consulte también Diferentes formas de cargar el objeto Engine para Windows Desarrollo multiplataforma en Java para Windows

Overview

Basic Usage Scenarios Implementation

Advanced Techniques

Agregar la biblioteca de FineReader Engine a un proyecto Java

Carga y descarga de FineReader Engine

Uso de Engine en aplicaciones Java multihilo

Manejo de errores

Llamada a métodos con parámetros de salida

Recolección de basura

Trabajar con enumeraciones

​Agregar la biblioteca de FineReader Engine a un proyecto Java

​Carga y descarga de FineReader Engine

​Uso de Engine en aplicaciones Java multihilo

​Manejo de errores

​Llamada a métodos con parámetros de salida

​Recolección de basura

​Trabajar con enumeraciones

Agregar la biblioteca de FineReader Engine a un proyecto Java

Carga y descarga de FineReader Engine

Uso de Engine en aplicaciones Java multihilo

Manejo de errores

Llamada a métodos con parámetros de salida

Recolección de basura

Trabajar con enumeraciones