Utiliser Java avec FRE for Windows

Cette rubrique s’applique à FRE for Windows.

Ajout de la bibliothèque FineReader Engine à un projet Java

ABBYY FineReader Engine comprend un fichier com.abbyy.FREngine-%BUILD_ID%.jar, qui contient la bibliothèque de classes Java pour FineReader Engine. Vous pouvez le trouver dans le dossier IncJava. Le chemin d’accès à ce fichier peut être indiqué dans le paramètre classpath sur la ligne de commande ainsi que dans les paramètres du projet de différents environnements de développement Java. Exemple :

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

%JDK% correspond au chemin d’accès du kit de développement Java.

Consultez la liste des kits de développement Java pris en charge dans Configuration système requise.

Chargement et déchargement de FineReader Engine

Vous pouvez utiliser la classe statique Engine pour charger l’objet Engine. La classe Engine fournit des méthodes qui correspondent aux fonctions d’ABBYY FineReader Engine pour charger et décharger Engine :

Fonction	Méthode de la classe Engine	Signature de la méthode de la classe 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;`

Exemple de code

import com.abbyy.FREngine.*;
public class Hello {
    public static void main( String[] args )
    {
        try {
            // Charger Engine avec une licence en ligne
            engine = Engine.InitializeEngine( dllPath, customerProjectId, LicensePath, LicensePassword, "", "", false );
            try {
                // Charger un profil prédéfini
                engine.LoadPredefinedProfile( "DocumentConversion_Accuracy" );
                // Traiter les images
                IFRDocument document = engine.CreateFRDocument();
                ...
            } finally {
                engine = null;
                System.runFinalization();
                Engine.DeinitializeEngine();
            }
        } catch( Exception ex ) {
            trace( ex.getMessage() );
        }
    }
    private IEngine engine = null;
...
}

Pour charger Engine au moyen de COM, utilisez les méthodes GetEngineInprocLoader ou GetEngineOutprocLoader. Consultez la description de l’interface IEngineLoader pour plus de détails. Si vous utilisez la méthode GetEngineOutprocLoader pour le chargement, vous n’avez pas besoin d’appeler la méthode IHostProcessControl::SetClientProcessId, car le processus parent sera défini automatiquement.

Si vous développez votre application sous Windows mais prévoyez de l’exécuter sous Linux, n’utilisez pas ces méthodes pour charger Engine. Utilisez uniquement la méthode InitializeEngine décrite ci-dessus. Cette limitation est due au fait que les objets implémentant IEngineLoader ne sont pas disponibles sous Linux.

Exemple de code avec InprocLoader

import com.abbyy.FREngine.*;
// Chargement d’Engine avec une licence en ligne
engineLoader = Engine.GetEngineInprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Déchargement d’Engine
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

Exemple de code avec OutprocLoader

import com.abbyy.FREngine.*;
// Chargement d’Engine avec une licence en ligne
engineLoader = Engine.GetEngineOutprocLoader();
engine = engineLoader.InitializeEngine( customerProjectId, LicensePath, LicensePassword, "", "", false );
...
// Déchargement d’Engine
engine = null;
System.runFinalization();
engineLoader.ExplicitlyUnload();
engineLoader = null;
System.runFinalization();

Pour travailler avec l’objet Engine créé via un chargeur Engine, la classe Engine fournit des méthodes qui appellent les fonctions COM correspondantes afin de marshaller le pointeur d’interface entre les threads :

Méthode	Signature	Commentaire
MarshalInterface	`long MarshalInterface();`	Appelle la fonction COM CoMarshalInterface pour marshaller l’interface IEngine. Cette méthode doit être appelée sur le thread où Engine a été créé, afin de garantir que les données nécessaires à la création d’un objet proxy sur un autre thread seront disponibles. Retourne le handle des données de marshaling.
UnmarshalInterface	`csharp IEngine UnmarshalInterface( long handle );`	Appelle la fonction COM CoUnmarshalInterface pour démarshaller l’interface IEngine, c’est-à-dire créer un objet proxy avec lequel le processus client pourra interagir de la même manière qu’avec Engine lui-même. Prend en paramètre d’entrée le handle des données de marshaling (retourné par la méthode MarshalInterface) et retourne un pointeur vers l’interface IEngine.

Le fichier com.abbyy.FREngine-%BUILD_ID%.jar est une archive auto-extractible qui est extraite sur votre machine lors de la première utilisation de l’API Java FineReader Engine. Le dossier dans lequel les fichiers sont extraits par défaut est Inc\Java pour Windows. Si vous devez utiliser un autre dossier, appelez la méthode Engine.SetJNIDllFolder avant de charger Engine à l’aide de l’une des méthodes décrites ci-dessus. Pour connaître le dossier actuellement défini pour l’extraction de l’archive, appelez Engine.GetJNIDllFolder.

Utiliser Engine dans des applications Java multithread

Pour les applications Java multithread, vous pouvez utiliser la classe EnginesPool, qui offre une solution complète pour créer et gérer un pool d’objets FineReader Engine. Cette classe implémente l’interface java.lang.Runnable.

public class EnginesPool implements Runnable;

Les méthodes de la classe EnginesPool sont répertoriées ci-dessous.

Method	Signature	Comment
constructor	`public EnginesPool( int enginesCount, int waitingEngineTimeout, String customerProjectId, String licensePath, String licensePassword, String dataFolder, String tempFolder, boolean isSharedCPUCoresMode ) throws Exception;`	Crée un nouveau pool de `enginesCount` Engines. `waitingEngineTimeout` définit le délai d’attente pour `EnginesPool.GetEngine`. Les autres paramètres sont identiques à ceux de InitializeEngine
GetEngine	`csharp public IEngine GetEngine() throws Exception;`	Obtient une instance d’Engine du pool. Déclenche une exception si le délai `waitingEngineTimeout` est dépassé.
ReleaseEngine	`csharp public void ReleaseEngine( IEngine engine, boolean isRecycleRequired ) throws Exception;`	Replace une instance d’Engine dans le pool. Si `isRecycleRequired` vaut true, cette instance est supprimée et remplacée par une nouvelle (même si la limite d’utilisation n’est pas atteinte ou si le recyclage automatique est désactivé).
SetAutoRecycleUsageCount	`public void SetAutoRecycleUsageCount( int value );`	Définit combien de fois une même instance d’Engine de ce pool peut être réutilisée avant d’être recyclée, c’est-à-dire supprimée puis remplacée automatiquement par une nouvelle. Cette valeur peut être définie sur 0 pour désactiver tout recyclage automatique (seul le recyclage manuel via `ReleaseEngine` sera alors possible). La valeur par défaut est 0 (aucun recyclage automatique).
GetAutoRecycleUsageCount	`public int GetAutoRecycleUsageCount();`	Obtient la limite de réutilisation d’une instance d’Engine pour ce pool.
UnloadEngines	`public void UnloadEngines() throws Exception;`	Décharge tous les Engines et désinitialise le pool.

Consultez l’exemple de code EnginesPool pour voir un exemple d’utilisation de la classe EnginesPool.

Gestion des erreurs

ABBYY FineReader Engine peut lever des exceptions des types suivants :

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

L’exception com.abbyy.FREngine.EngineException hérite de java.lang.Exception et contient une méthode supplémentaire, int getHResult, qui renvoie le code HRESULT de l’erreur qui s’est produite. Pour une exception de ce type, vous pouvez non seulement récupérer le message d’erreur à l’aide de la méthode getMessage(), mais aussi le code d’erreur.

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

Appel de méthodes avec des paramètres out

Plusieurs méthodes de l’API ABBYY FineReader Engine comportent des paramètres out, qui reçoivent une nouvelle valeur après l’appel de la méthode et doivent être passés par référence. Ces paramètres sont indiqués dans la bibliothèque de types et dans la description des méthodes de cette documentation développeur comme [out] ou [in, out]. Lorsque vous travaillez avec ABBYY FineReader Engine en Java, vous devez utiliser une classe Ref spéciale pour passer un paramètre par référence. Voir les exemples ci-dessous. Exemple dans lequel les paramètres out sont passés par référence à la méthode IFRPage::FindPageSplitPosition :

Exemple de code pour les paramètres 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();

Exemple dans lequel les paramètres in/out sont passés par référence à la méthode ICoordinatesConverter::ConvertCoordinates :

Exemple de code pour les paramètres 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();

L’exemple suivant montre les paramètres out de type tableau passés par référence à la méthode IPlainText::GetCharacterData :

Exemple de code pour les paramètres out de type tableau

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

Gestion des ressources

FineReader Engine prend en charge l’interface AutoCloseable, ce qui vous permet d’utiliser l’instruction try pour gérer les ressources allouées aux objets. Cela signifie qu’une fois le bloc try terminé, toutes les ressources allouées sont fermées automatiquement, sans qu’il soit nécessaire d’appeler explicitement des méthodes de fermeture. Nous vous recommandons d’utiliser l’instruction try pour tous les objets de votre code (voir l’exemple ci-dessous) :

Exemple de code

try( IFRDocument document = engine.CreateDocument() )
 {
  // Ajouter une image à un document
  document.AddImageFile( imagePath, null, null );
  ...
  // Enregistrer les résultats au format PDF
  document.Export( pdfExportPath, FileExportFormatEnum.FEF_PDF, pdfParams );
 }

Utilisation de HGLOBAL Certaines méthodes de l’API ABBYY FineReader Engine prennent comme paramètre d’entrée un handle HGLOBAL vers un bloc de mémoire (passé en tant que __int64). Comme HGLOBAL est spécifique à Windows, ces méthodes reçoivent à la place, dans le wrapper Java, le contenu du bloc de mémoire sous forme de byte[]. Voir la liste de ces méthodes :

méthodes LoadImageDocFromMemory et OpenImageFileFromMemory de l’objet Engine
méthode LoadFromMemory fournie par de nombreux objets
méthode AddImageFileFromMemory de l’objet FRDocument
méthode AddFromMemory de l’objet PDFAttachments

En revanche, les méthodes qui renvoient un objet Handle le renvoient également dans le wrapper Java.

Utilisation des énumérations

Les méthodes et les propriétés qui acceptent une combinaison de constantes d’énumération exigent que la valeur int soit transmise à la méthode ou à la propriété. Pour obtenir la valeur int d’une constante d’énumération, utilisez la méthode getValue, prise en charge par toutes les énumérations. Voici un exemple de code qui montre comment définir la propriété BwPictureFormats de l’objet PDFPictureCompressionParams :

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

Voir aussi Différentes façons de charger l’objet Engine pour Windows Développement multiplateforme en Java pour Windows

​Ajout de la bibliothèque FineReader Engine à un projet Java

​Chargement et déchargement de FineReader Engine

​Utiliser Engine dans des applications Java multithread

​Gestion des erreurs

​Appel de méthodes avec des paramètres out

​Gestion des ressources

​Utilisation des énumérations

Ajout de la bibliothèque FineReader Engine à un projet Java

Chargement et déchargement de FineReader Engine

Utiliser Engine dans des applications Java multithread

Gestion des erreurs

Appel de méthodes avec des paramètres out

Gestion des ressources

Utilisation des énumérations