Java mit FRE for Windows verwenden

Dieses Thema bezieht sich auf FRE for Windows.

Einbinden der FineReader Engine-Bibliothek in ein Java-Projekt

ABBYY FineReader Engine enthält die Datei com.abbyy.FREngine-%BUILD_ID%.jar, die die Java-Klassenbibliothek für FineReader Engine umfasst. Sie finden sie im IncJava-Ordner. Der Pfad zu dieser Datei kann in der Befehlszeile über den Parameter classpath sowie in den Projekteinstellungen verschiedener Java-Entwicklungsumgebungen angegeben werden. Beispiel:

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

%JDK% ist der Pfad zum Java Development Kit.

Eine Liste der unterstützten Java Development Kits finden Sie unter Systemanforderungen.

Laden und Entladen von FineReader Engine

Sie können die statische Klasse Engine verwenden, um das Engine-Objekt zu laden. Die Klasse Engine stellt Methoden bereit, die den ABBYY FineReader Engine-Funktionen zum Laden und Entladen der Engine entsprechen:

Funktion	Methode der Klasse Engine	Signatur der Methode der Klasse 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;`

Beispielcode

import com.abbyy.FREngine.*;
public class Hello {
    public static void main( String[] args )
    {
        try {
            // Engine mit Online-Lizenz laden
            engine = Engine.InitializeEngine( dllPath, customerProjectId, LicensePath, LicensePassword, "", "", false );
            try {
                // Ein vordefiniertes Profil laden
                engine.LoadPredefinedProfile( "DocumentConversion_Accuracy" );
                // Bilder verarbeiten
                IFRDocument document = engine.CreateFRDocument();
                ...
            } finally {
                engine = null;
                System.runFinalization();
                Engine.DeinitializeEngine();
            }
        } catch( Exception ex ) {
            trace( ex.getMessage() );
        }
    }
    private IEngine engine = null;
...
}

Um die Engine über COM zu laden, verwenden Sie die Methoden GetEngineInprocLoader oder GetEngineOutprocLoader. Ausführliche Informationen finden Sie in der Beschreibung der IEngineLoader-Schnittstelle. Wenn Sie zum Laden die Methode GetEngineOutprocLoader verwenden, müssen Sie die Methode IHostProcessControl::SetClientProcessId nicht aufrufen, da der übergeordnete Prozess automatisch festgelegt wird.

Wenn Sie Ihre Anwendung unter Windows entwickeln, sie aber unter Linux ausführen möchten, verwenden Sie diese Methoden nicht zum Laden der Engine. Verwenden Sie nur die oben beschriebene Methode InitializeEngine. Diese Einschränkung besteht, weil Objekte, die IEngineLoader implementieren, unter Linux nicht verfügbar sind.

Beispielcode mit InprocLoader

import com.abbyy.FREngine.*;
// Engine mit Online-Lizenz laden
engineLoader = Engine.GetEngineInprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Engine entladen
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

Beispielcode mit OutprocLoader

import com.abbyy.FREngine.*;
// Engine mit Online-Lizenz laden
engineLoader = Engine.GetEngineOutprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Engine entladen
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

Für die Arbeit mit dem Engine-Objekt, das über einen Engine-Loader erstellt wurde, stellt die Klasse Engine Methoden bereit, die die entsprechenden COM-Funktionen aufrufen, um den Schnittstellenzeiger über Threadgrenzen hinweg zu marshalen:

Methode	Signatur	Kommentar
MarshalInterface	`long MarshalInterface();`	Ruft die COM-Funktion CoMarshalInterface auf, um die IEngine-Schnittstelle zu marshalen. Diese Methode sollte in dem Thread aufgerufen werden, in dem die Engine erstellt wurde, damit die Daten verfügbar sind, die zum Erstellen eines Proxy-Objekts in einem anderen Thread benötigt werden. Gibt das Handle für die Marshaling-Daten zurück.
UnmarshalInterface	`csharp IEngine UnmarshalInterface( long handle );`	Ruft die COM-Funktion CoUnmarshalInterface auf, um das Marshaling der IEngine-Schnittstelle aufzuheben, d. h. ein Proxy-Objekt zu erstellen, mit dem der Client-Prozess auf dieselbe Weise interagieren kann wie mit der Engine selbst. Nimmt das Handle für die Marshaling-Daten (das von der Methode MarshalInterface zurückgegeben wird) als Eingabeparameter entgegen und gibt einen Zeiger auf die IEngine-Schnittstelle zurück.

Die Datei com.abbyy.FREngine-%BUILD_ID%.jar ist ein selbstentpackendes Archiv, das bei der ersten Verwendung der FineReader Engine Java API auf Ihrem Rechner entpackt wird. Der Standardordner, in den der Inhalt entpackt wird, ist unter Windows Inc\Java. Wenn Sie einen anderen Ordner verwenden möchten, rufen Sie vor dem Laden der Engine mit einer der oben beschriebenen Methoden die Methode Engine.SetJNIDllFolder auf. Um herauszufinden, welcher Ordner derzeit zum Entpacken des Archivs festgelegt ist, rufen Sie die Methode Engine.GetJNIDllFolder auf.

Einsatz von Engine in mehrthreadigen Java-Anwendungen

Für mehrthreadige Java-Anwendungen können Sie die Klasse EnginesPool verwenden, die eine vollständige Lösung zum Erstellen und Verwalten eines Pools von FineReader Engine-Objekten bietet. Diese Klasse implementiert die Schnittstelle java.lang.Runnable.

public class EnginesPool implements Runnable;

Die Methoden der Klasse EnginesPool sind unten aufgeführt.

Methode	Signatur	Kommentar
constructor	`public EnginesPool( int enginesCount, int waitingEngineTimeout, String customerProjectId, String licensePath, String licensePassword, String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception;`	Erstellt einen neuen Pool mit `enginesCount` Engine-Instanzen. `waitingEngineTimeout` legt das Timeout für `EnginesPool.GetEngine` fest. Die übrigen Parameter sind dieselben wie bei InitializeEngine
GetEngine	`csharp public IEngine GetEngine() throws Exception;`	Ruft eine Engine-Instanz aus dem Pool ab. Löst eine Ausnahme aus, wenn `waitingEngineTimeout` überschritten wird.
ReleaseEngine	`csharp public void ReleaseEngine( IEngine engine, boolean isRecycleRequired ) throws Exception;`	Gibt eine Engine-Instanz an den Pool zurück. Wenn `isRecycleRequired` den Wert `true` hat, wird diese Instanz gelöscht und durch eine neue ersetzt (auch wenn das Nutzungslimit noch nicht erreicht ist oder automatisches Recycling deaktiviert ist).
SetAutoRecycleUsageCount	`public void SetAutoRecycleUsageCount( int value );`	Legt fest, wie oft eine einzelne Engine-Instanz in diesem Pool wiederverwendet werden kann, bevor die Instanz recycelt wird, also gelöscht und automatisch durch eine neue ersetzt wird. Der Wert kann auf `0` gesetzt werden, damit niemals automatisch recycelt wird (nur manuelles Recycling ist dann über `ReleaseEngine` möglich). Standardwert ist `0` (niemals automatisch recyceln).
GetAutoRecycleUsageCount	`public int GetAutoRecycleUsageCount();`	Gibt das Wiederverwendungslimit für Engine-Instanzen in diesem Pool zurück.
UnloadEngines	`public void UnloadEngines() throws Exception;`	Entlädt alle Engine-Instanzen und gibt den Pool frei.

Ein Beispiel für die Verwendung der Klasse EnginesPool finden Sie im Codebeispiel EnginesPool.

Fehlerbehandlung

ABBYY FineReader Engine kann Ausnahmen der folgenden Typen auslösen:

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

Die Ausnahme com.abbyy.FREngine.EngineException erbt von java.lang.Exception und enthält eine zusätzliche Methode, int getHResult, die den HRESULT-Code des aufgetretenen Fehlers zurückgibt. Bei einer Ausnahme dieses Typs können Sie nicht nur die Fehlermeldung mit der Methode getMessage() abrufen, sondern auch den Fehlercode.

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

Methoden mit Out-Parametern aufrufen

In der ABBYY FineReader Engine API gibt es mehrere Methoden mit Out-Parametern, die nach dem Methodenaufruf einen neuen Wert erhalten und per Referenz übergeben werden müssen. Diese Parameter sind in der Typbibliothek und in den Methodenbeschreibungen in dieser Developer’s Help als [out] oder [in, out] gekennzeichnet. Wenn Sie mit ABBYY FineReader Engine in Java arbeiten, müssen Sie eine spezielle Klasse Ref verwenden, um einen Parameter per Referenz zu übergeben. Siehe die folgenden Beispiele. Beispiel, in dem die Out-Parameter per Referenz an die Methode IFRPage::FindPageSplitPosition übergeben werden:

Beispielcode für Out-Parameter

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

Beispiel, in dem die In/Out-Parameter per Referenz an die Methode ICoordinatesConverter::ConvertCoordinates übergeben werden:

Beispielcode für In/Out-Parameter

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

Das folgende Beispiel zeigt Array-Out-Parameter, die per Referenz an die Methode IPlainText::GetCharacterData übergeben werden:

Beispielcode für Array-Out-Parameter

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

Speicherbereinigung

FineReader Engine unterstützt die AutoCloseable-Schnittstelle, sodass Sie die try-Anweisung verwenden können, um mit den für Objekte reservierten Ressourcen zu arbeiten. Das bedeutet, dass nach Erreichen des Endes des try-Blocks alle zugewiesenen Ressourcen automatisch geschlossen werden, ohne dass Schließmethoden explizit aufgerufen werden müssen. Wir empfehlen, die try-Anweisung für alle Objekte in Ihrem Code zu verwenden (siehe Beispiel unten):

Beispielcode

try( IFRDocument document = engine.CreateDocument() )
 {
  // Bild zu einem Dokument hinzufügen
  document.AddImageFile( imagePath, null, null );
  ...
  // Ergebnisse als PDF speichern
  document.Export( pdfExportPath, FileExportFormatEnum.FEF_PDF, pdfParams );
 }

Arbeiten mit HGLOBAL Einige Methoden in der ABBYY FineReader Engine API erwarten als input parameter ein HGLOBAL-Handle auf einen Speicherblock (übergeben als __int64). Da HGLOBAL ein Windows-spezifisches Konstrukt ist, erhalten diese Methoden im Java-Wrapper stattdessen den Inhalt des Speicherblocks als byte[]. Zu diesen Methoden gehören:

die Methoden LoadImageDocFromMemory und OpenImageFileFromMemory des Engine-Objekts
die von vielen Objekten bereitgestellte Methode LoadFromMemory
die Methode AddImageFileFromMemory des FRDocument-Objekts
die Methode AddFromMemory des PDFAttachments-Objekts

Umgekehrt geben Methoden, die ein Handle-Objekt zurückgeben, dieses auch im Java-Wrapper zurück.

Arbeiten mit Aufzählungen

Bei Methoden und Eigenschaften, die eine Kombination von Aufzählungskonstanten akzeptieren, muss der int-Wert an die Methode bzw. Eigenschaft übergeben werden. Um den int-Wert einer Aufzählungskonstante zu ermitteln, verwenden Sie die Methode getValue, die von allen Aufzählungen unterstützt wird. Hier ist Beispielcode, der zeigt, wie die Eigenschaft BwPictureFormats des Objekts PDFPictureCompressionParams festgelegt wird:

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

Siehe auch Unterschiedliche Möglichkeiten zum Laden des Engine-Objekts für Windows Plattformübergreifende Entwicklung in Java für Windows

​Einbinden der FineReader Engine-Bibliothek in ein Java-Projekt

​Laden und Entladen von FineReader Engine

​Einsatz von Engine in mehrthreadigen Java-Anwendungen

​Fehlerbehandlung

​Methoden mit Out-Parametern aufrufen

​Speicherbereinigung

​Arbeiten mit Aufzählungen

Einbinden der FineReader Engine-Bibliothek in ein Java-Projekt

Laden und Entladen von FineReader Engine

Einsatz von Engine in mehrthreadigen Java-Anwendungen

Fehlerbehandlung

Methoden mit Out-Parametern aufrufen

Speicherbereinigung

Arbeiten mit Aufzählungen