EasyPoi est une bibliothèque Java conçue pour simplifier les interactions avec Microsoft Excel et Word, en encapsulant la complexité d'Apache POI. Son objectif est de permettre aux développeurs, même novices, de réaliser des opérations d'importation et d'exportation complexes via des annotations simples et un moteur de templates intuitif.

Caractéristiques principales d'EasyPoi

• Conception intuitive : Une prise en main rapide grâce à une abstraction de haut niveau.
• Extensibilité : Des interfaces riches permettant de personnaliser le comportement par défaut.
• Productivité : De nombreuses valeurs par défaut pour réduire le volume de code (approche "write less, do more").
• Intégration Web : Support natif d'AbstractView pour faciliter les exports dans les frameworks comme Spring MVC.

Scénarios d'utilisation pour l'exportation

1. Export standard (données < 50 000 lignes) : Utilisation des annotations sur les POJO via ExcelExportUtil.exportExcel.
2. Colonnes dynamiques : Lorsque le nombre de colonnes est variable, passage par une liste d'entités ExcelExportEntity.
3. Flux de données massives (jusqu'à 1 million de lignes) : Utilisation de exportBigExcel pour optimiser la mémoire.
4. Mise en forme complexe : Utilisation de templates Excel avec TemplateExportParams.
5. Multi-feuilles (Sheets) : Export de plusieurs styles ou datasets dans un seul fichier via des maps de paramètres.
6. Transformation HTML : Conversion directe d'un flux HTML vers un format Excel via ExcelXorHtmlUtil.htmlToExcel.
7. Très gros volumes (> 1 million) : Passage au format CSV avec CsvExportUtil.exportCsv.

Scénarios d'utilisation pour l'importation

• Import classique : Extraction de données vers une liste d'objets ou de Maps via ExcelImportUtil.importExcel.
• Import avec validation : Utilisation de importExcelMore pour récupérer les résultats incluant les erreurs de validation.
• Traitement de gros fichiers : Utilisation du mode SAX avec IReadHandler pour minimiser l'empreinte mémoire.
• Import CSV : Gestion des fichiers plats pour les volumes dépassant les limites d'Excel.

Syntaxe des expressions pour les templates

EasyPoi utilise une syntaxe spécifique au sein des fichiers templates (cellules Excel) pour dynamiser le contenu :

• {{valeur}} : Affiche la variable.
• {{test ? fixe1 : fixe2}} : Opérateur ternaire pour l'affichage conditionnel.
• n: : Force le type numérique dans la cellule.
• fd:(obj;yyyy-MM-dd) : Formatage d'un objet Date.
• fn:(obj;###.00) : Formatage d'un nombre.
• fe: : Itération sur une liste pour générer de nouvelles lignes.
• !if:(condition) : Suppression conditionnelle d'une colonne.

Exemples d'implémentation

1. Définition d'un modèle avec annotations

Les annotations permettent de lier les champs de votre classe Java aux colonnes du fichier Excel.

@ExcelTarget("formationEntity")
public class Formation implements Serializable {
    private String id;

    @Excel(name = "Intitulé du Cours", orderNum = "1", needMerge = true)
    private String intitule;

    @ExcelEntity(id = "profPrincipal")
    private Formateur formateur;

    @ExcelCollection(name = "Liste des Apprenants", orderNum = "3")
    private List<Apprenant> apprenants;
    
    // Getters et Setters...
}

2. Exportation simple vers un Workbook

Il suffit de fournir les paramètres d'export, la classe de référence et la liste de données.

ExportParams configuration = new ExportParams("Planning Annuel", "Exporté par Admin", "Feuille1");
Workbook workbook = ExcelExportUtil.exportExcel(configuration, Formation.class, maListeDeFormations);

3. Exportation basée sur une structure Map

Utile lorsque la structure des données est dynamique et ne peut être définie par une classe fixe.

List<ExcelExportEntity> colonnes = new ArrayList<>();
colonnes.add(new ExcelExportEntity("Désignation", "label"));
colonnes.add(new ExcelExportEntity("Prix Unitaire", "prix"));

List<Map<String, Object>> donnees = new ArrayList<>();
Map<String, Object> ligne = new HashMap<>();
ligne.put("label", "Produit A");
ligne.put("prix", 150.50);
donnees.add(ligne);

Workbook wb = ExcelExportUtil.exportExcel(new ExportParams("Catalogue", "Ventes"), colonnes, donnees);

4. Importation de données avec validation

EasyPoi permet de valider les données entrantes (ex: via des annotations de validation Hibernate) lors de l'import.

ImportParams optionsImport = new ImportParams();
optionsImport.setTitleRows(1);
optionsImport.setHeadRows(1);
optionsImport.setNeedSave(false);

ExcelImportResult<Formation> resultat = ExcelImportUtil.importExcelVerify(
    new File("data_source.xlsx"), 
    Formation.class, 
    optionsImport
);

for (Formation f : resultat.getList()) {
    System.out.println("Donnée valide : " + f.getIntitule());
}

5. Intégration avec Spring MVC

EasyPoi propose des vues dédiées pour simplifier le retour des fichiers Excel dans les contrôleurs Web.

@GetMapping("/telecharger-excel")
public String genererExcel(ModelMap model) {
    List<Formation> data = formationService.findAll();
    
    model.put(NormalExcelConstants.FILE_NAME, "Rapport_Formations");
    model.put(NormalExcelConstants.CLASS, Formation.class);
    model.put(NormalExcelConstants.PARAMS, new ExportParams("Liste des Cours", "Système"));
    model.put(NormalExcelConstants.DATA_LIST, data);
    
    return NormalExcelConstants.JEECG_EXCEL_VIEW;
}

Considérations techniques : XLS vs XLSX

Le choix du format impacte les performances de votre application :

• Vitesse : Le format XLS est généralemetn 2 à 3 fois plus rapide à générer que le XLSX.
• Poids : Le format XLSX est nettement plus compressé et occupe moins d'espace disque.
• Limites : Le format XLS est limité à 65 536 lignes, tandis que le XLSX peut en contenir plus d'un million.