Vai al contenuto principale
Questo argomento è relativo a FRE for Windows.

​
Aggiunta della libreria FineReader Engine a un progetto Java

ABBYY FineReader Engine include un file com.abbyy.FREngine-%BUILD_ID%.jar, che contiene la libreria di classi Java per FineReader Engine. È possibile trovarlo nella cartella Inc\Java. Il percorso di questo file può essere specificato nel parametro classpath della riga di comando e nelle impostazioni del progetto nei vari ambienti di sviluppo Java. Esempio: 
%JDK%\bin\Javac -classpath <path>/com.abbyy.FREngine-%BUILD_ID%.jar Hello.java
%JDK% è il percorso di Java Development Kit.
Consulta l’elenco dei Java Development Kit supportati in Requisiti di sistema.

​
Caricamento e scaricamento di FineReader Engine

È possibile utilizzare la classe statica Engine per caricare l’oggetto Engine. La classe Engine fornisce metodi che corrispondono alle funzioni di ABBYY FineReader Engine per caricare e scaricare Engine:
FunzioneMetodo della classe EngineFirma del metodo della classe Engine
InitializeEngineInitializeEnginecsharp static public IEngine InitializeEngine( String dllFolder, String customerProjectId, String licensePath, String licensePassword, String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception;
DeinitializeEngineDeinitializeEnginestatic public void DeinitializeEngine() throws Exception;
import com.abbyy.FREngine.*;
public class Hello {
    public static void main( String[] args )
    {
        try {
            // Carica Engine con licenza online
            engine = Engine.InitializeEngine( dllPath, customerProjectId, LicensePath, LicensePassword, "", "", false );
            try {
                // Carica un profilo predefinito
                engine.LoadPredefinedProfile( "DocumentConversion_Accuracy" );
                // Elabora le immagini
                IFRDocument document = engine.CreateFRDocument();
                ...
            } finally {
                engine = null;
                System.runFinalization();
                Engine.DeinitializeEngine();
            }
        } catch( Exception ex ) {
            trace( ex.getMessage() );
        }
    }
    private IEngine engine = null;
...
}
Per caricare Engine tramite COM, utilizzare i metodi GetEngineInprocLoader o GetEngineOutprocLoader. Per i dettagli, vedere la descrizione dell’interfaccia IEngineLoader. Se si utilizza il metodo GetEngineOutprocLoader per il caricamento, non è necessario chiamare il metodo IHostProcessControl::SetClientProcessId, poiché il processo padre verrà impostato automaticamente.
Se si sviluppa l’applicazione su Windows ma si intende eseguirla su Linux, non utilizzare questi metodi per caricare Engine. Utilizzare solo il metodo InitializeEngine descritto sopra. Questa limitazione è dovuta al fatto che gli oggetti che implementano IEngineLoader non sono disponibili su Linux.
import com.abbyy.FREngine.*;
// Caricamento di Engine con licenza online
engineLoader = Engine.GetEngineInprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Scaricamento di Engine
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

import com.abbyy.FREngine.*;
// Caricamento di Engine con licenza online
engineLoader = Engine.GetEngineOutprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Scaricamento di Engine
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();
Per lavorare con l’oggetto Engine creato tramite un loader del motore, la classe Engine fornisce metodi che chiamano le corrispondenti funzioni COM per eseguire il marshalling del puntatore all’interfaccia tra thread:
MetodoFirmaCommento
MarshalInterfacelong MarshalInterface();Chiama la funzione COM CoMarshalInterface per eseguire il marshalling dell’interfaccia IEngine. Questo metodo deve essere chiamato nel thread in cui è stato creato il motore, per garantire che siano disponibili i dati necessari per creare un oggetto proxy in un altro thread. Restituisce l’handle dei dati di marshalling.
UnmarshalInterfacecsharp IEngine UnmarshalInterface( long handle ); Chiama la funzione COM CoUnmarshalInterface per eseguire l’unmarshalling dell’interfaccia IEngine, cioè creare un oggetto proxy con cui il processo client potrà interagire nello stesso modo in cui interagisce con il motore stesso. Accetta come parametro di input l’handle dei dati di marshalling (restituito dal metodo MarshalInterface) e restituisce un puntatore all’interfaccia IEngine.
Il file com.abbyy.FREngine-%BUILD_ID%.jar è un archivio autoestraente che viene decompresso sul computer al primo utilizzo della Java API di FineReader Engine. La cartella predefinita in cui viene decompresso il contenuto è Inc\Java per Windows. Se è necessario utilizzare un’altra cartella, chiamare il metodo Engine.SetJNIDllFolder prima di caricare Engine con uno dei metodi descritti sopra. Per sapere quale cartella è attualmente impostata per la decompressione dell’archivio, chiamare Engine.GetJNIDllFolder.

​
Utilizzo di Engine nelle applicazioni Java multithread

Per le applicazioni Java multithread, è possibile usare la classe EnginesPool, che offre una soluzione completa per creare e gestire un pool di oggetti FineReader Engine. Questa classe implementa l’interfaccia java.lang.Runnable. 
public class EnginesPool implements Runnable;
I metodi della classe EnginesPool sono elencati di seguito.
MetodoSignatureCommento
constructorpublic EnginesPool( int enginesCount, int waitingEngineTimeout, String customerProjectId, String licensePath, String licensePassword, String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception;Crea un nuovo pool di enginesCount istanze di Engine. Il parametro waitingEngineTimeout definisce il timeout per EnginesPool.GetEngine. Gli altri parametri sono gli stessi di InitializeEngine
GetEnginecsharp public IEngine GetEngine() throws Exception; Ottiene un’istanza di Engine dal pool. Genera un’eccezione se viene superato il timeout waitingEngineTimeout.
ReleaseEnginecsharp public void ReleaseEngine( IEngine engine, boolean isRecycleRequired ) throws Exception; Restituisce un’istanza di Engine al pool. Se isRecycleRequired è true, elimina questa istanza e la sostituisce con una nuova (anche se il limite di utilizzo non è stato raggiunto o il riciclo automatico è disabilitato).
SetAutoRecycleUsageCountpublic void SetAutoRecycleUsageCount( int value );Imposta il numero di volte in cui una singola istanza di Engine in questo pool può essere riutilizzata prima di essere riciclata, cioè eliminata e sostituita automaticamente con una nuova. Il valore può essere impostato su 0 per non eseguire mai il riciclo automatico (sarà possibile solo il riciclo manuale, tramite ReleaseEngine). Il valore predefinito è 0 (nessun riciclo automatico).
GetAutoRecycleUsageCountpublic int GetAutoRecycleUsageCount();Restituisce il limite di riutilizzo di un’istanza di Engine per questo pool.
UnloadEnginespublic void UnloadEngines() throws Exception;Scarica tutti gli Engine e deinizializza il pool.
Vedi l’esempio di codice EnginesPool per un esempio di utilizzo della classe EnginesPool.

​
Gestione degli errori

ABBYY FineReader Engine può generare eccezioni dei seguenti tipi:
  • java.lang.OutOfMemoryError
  • com.abbyy.FREngine.EngineException
L’eccezione com.abbyy.FREngine.EngineException eredita da java.lang.Exception e contiene un metodo aggiuntivo, int getHResult, che restituisce il codice HRESULT dell’errore verificatosi. Per un’eccezione di questo tipo, è possibile non solo ottenere il messaggio di errore tramite il metodo getMessage(), ma anche recuperarne il codice. 
try {
    ...
} catch( Exception ex ) {
    displayMessage( "Message = " + ex.getMessage() );
    if( ex instanceof EngineException ) {
        displayMessage( "HResult = " + Integer.toString( ( ( EngineException )ex ).getHResult() ) );
    }
}

​
Chiamata di metodi con parametri out

Nell’API di ABBYY FineReader Engine sono presenti diversi metodi con parametri out a cui viene assegnato un nuovo valore dopo la chiamata del metodo e che devono essere passati per riferimento. Questi parametri sono contrassegnati nella libreria dei tipi e nelle descrizioni dei metodi in questa Guida per sviluppatori come [out] o [in, out]. Quando si lavora con ABBYY FineReader Engine in Java, è necessario utilizzare una speciale classe Ref per passare un parametro per riferimento. Vedi gli esempi riportati di seguito. Esempio in cui i parametri out vengono passati per riferimento al metodo IFRPage::FindPageSplitPosition: 
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();
Esempio in cui i parametri in/out vengono passati per riferimento al metodo ICoordinatesConverter::ConvertCoordinates: 
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();
L’esempio seguente mostra i parametri out di tipo array passati per riferimento al metodo IPlainText::GetCharacterData: 
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[]>();

​
Garbage collection

FineReader Engine supporta l’interfaccia AutoCloseable, che consente di utilizzare l’istruzione try per accedere alle risorse allocate per gli oggetti. Ciò significa che, una volta raggiunta la fine del blocco try, tutte le risorse allocate verranno chiuse automaticamente, senza dover chiamare esplicitamente i metodi di chiusura. Si consiglia di utilizzare l’istruzione try per tutti gli oggetti nel codice (vedere l’esempio seguente): 
try( IFRDocument document = engine.CreateDocument() )
 {
  // Aggiunge un'immagine a un documento
  document.AddImageFile( imagePath, null, null );
  ...
  // Salva i risultati in PDF
  document.Export( pdfExportPath, FileExportFormatEnum.FEF_PDF, pdfParams );
 }
Utilizzo di HGLOBAL Alcuni metodi dell’API di ABBYY FineReader Engine accettano come parametro di input un handle HGLOBAL a un blocco di memoria (passato come __int64). Poiché HGLOBAL è un’entità specifica di Windows, nel wrapper Java questi metodi ricevono invece il contenuto del blocco di memoria come byte[]. Ecco l’elenco di questi metodi: D’altra parte, i metodi che restituiscono un oggetto Handle lo restituiscono anche nel wrapper Java.

​
Lavorare con le enumerazioni

I metodi e le proprietà che accettano una combinazione di costanti di enumerazione richiedono che al metodo o alla proprietà venga passato il valore int. Per ottenere il valore int di una costante di enumerazione, usare il metodo getValue, supportato da tutte le enumerazioni. Di seguito è riportato un esempio di codice che mostra come impostare la proprietà BwPictureFormats dell’oggetto PDFPictureCompressionParams: 
IPDFExportParams pep = engine.CreatePDFExportParams();
IPDFPictureCompressionParams ppcp = pep.getPictureCompressionParams();
ppcp.setBwPictureFormats(BwPictureFormatsEnum.BWPF_Auto.getValue());
Vedi anche Diversi modi per caricare l’oggetto Engine per Windows Sviluppo multipiattaforma in Java per Windows