Cours sur les principaux savoir-faire du Framework BIRT

Participez au vote ☆☆☆☆☆★★★★★

Génération de rapports BIRT à l'aide de la 'BIRT Design Engine API'

par flo_rian

Date de publication : 26 novembre 2009

Dernière mise à jour : 26 novembre 2009

Ce tutoriel, pour débutant, a pour objectif de vous présenter une méthode pour générer dynamiquement des rapports BIRT.

BIRT (The Business Intelligence and Reporting Tools) est un projet qui fournit deux outils majeurs :

- le moteur de visualisation de rapports. Il repose sur la REAPI : Report Design Engine API.

- le moteur de conception de rapports. Il repose sur la DEAPI : Design Engine API.

L'outil de conception graphique des rapports BIRT (présent dans Eclipse) ne suffit pas toujours lorsque le développeur doit implémenter BIRT dans son application web : en effet il arrive qu'il soit nécessaire de générer des rapports dynamiquement. La DEAPI de BIRT répond à ce besoin.

Ce tutoriel a pour objectif de présenter une façon de réaliser des rapports BIRT en utilisant la Design Engine API (API de conception des rapports BIRT).

Pour cela on se place dans un contexte assez simple :

- on dispose d'une base de données contenant un certain nombre d'éléments à visualiser : une liste de produits.

- on souhaite visualiser ces données dans un rapport en fonction du type de produit (alimentaire ou mobilier).

On va donc créer un rapport BIRT qui permet d'effectuer cette visualisation. L'utilisateur qui aura suivi ce tutoriel aura ensuite les bases nécessaires pour générer des rapports dynamiquement.

Il est nécessaire d'avoir au minimum la version java 1.5.x.

Téléchargeable depuis le site de Sun :

La version d'Eclipse utilisée dans ce tutoriel est Eclipse Ganimède 3.4.2.

Téléchargeable depuis le site d'Eclipse-BIRT :

La version de PostgreSql utilisée dans ce tutoriel est PostgreSql 8.2.

Téléchargeable depuis le site de PostgreSql :

La version du BIRT Runtime utilisé dans ce tutoriel est BIRT Runtime 2.3.2.2.

Téléchargeable depuis le site d'Eclipse-BIRT :

Dans l'espace de travail courant, créer un nouveau projet java.

Ensuite :

- Créer un dossier nommé 'runtime'. Dans ce dossier copier le contenu du répertoire 'birt-runtime-2_3_2' issu del'archive ''.

- Créer un dossier nommé 'reports'. Ce répertoire accueillera les futurs fichiers .rptdesign.

- Ajouter ensuite au Build Path l'ensemble des librairies contenues dans le répertoire 'runtime/ReportEngine/lib'.L'espace de travail est maintenant près pour la génération de rapports BIRT à partir de la DEAPI. Ci-dessous une copie d'écran de ce à quoi doit ressembler l'espace de travail.

Espace de travail

A propos du contenu du répertoire 'runtime'

Ce répertoire est constitué par :

- le répertoire 'about_files' : contient le fichier de licence Apache

- le répertoire WebViewerExample : arborescence de l'application web permettant de visualiser des rapports BIRT

- les fichier et : fichiers décrivant le cadre juridique pour l'utilisation de BIRT

- le fichier : fichier donnant une description générale sur BIRT et la façon de lancer BIRT en mode console.- le fichier : licence Eclipse

- le fichier : archive war du WebViewerExample- le répertoire ReportEngine : son contenu est explicité plus bas Le répertoire ReportEngine est constitué par :

- le répertoire 'configuration' : ce répertoire contient le fichier de configuration pour la gestion des moteurs BIRT.

- le répertoire 'lib' : ce répertoire contient les librairies utiles pour la manipulation des objets BIRT.

- le répertoire 'plugins' : ce répertoire contient les librairies nécessaires pour la gestion des moteurs BIRT.

- le répertoire 'samples' : ce répertoire contient des exemples de rapports au format rptdesign.

- le fichier '' : permet de créer des rapports au format pdf et html en mode console (à partir de fichiersrptdesign) dans un environnement windows.

- le fichier '' : permet de créer des rapports au format pdf et html en mode console (à partir de fichiersrptdesign) dans un environnement unix.

Le rapport BIRT se base sur une source de données constituée d'une table 'table_des_produits'. Il s'agit d'une table qui contient une liste de produits caractérisés par : - un identifiant

- un type

- un nom- un prix

Voici le script de création de la structure de données :

CREATE TABLE table_des_produits

(

id serial NOT NULL,

type_produit character varying,

nom character varying, prix character varying,

CONSTRAINT table_des_produits_pkey PRIMARY KEY (id)

)

WITHOUT OIDS;

ALTER TABLE table_des_produits OWNER TO postgres;

Voici le script d'insertion d'un jeu de données :

INSERT INTO table_des_produits (id, type_produit, nom, prix) VALUES

(1, 'alimentaire', 'Lot de 3 tablettes de chocolat', '5');

INSERT INTO table_des_produits (id, type_produit, nom, prix) VALUES

(2, 'alimentaire', 'saucisson', '8');

INSERT INTO table_des_produits (id, type_produit, nom, prix) VALUES

(3, 'alimentaire', 'reblochon', '11');

INSERT INTO table_des_produits (id, type_produit, nom, prix) VALUES (4, 'mobilier', 'bureau', '120');

INSERT INTO table_des_produits (id, type_produit, nom, prix) VALUES (5, 'mobilier', 'chaise', '70');

INSERT INTO table_des_produits (id, type_produit, nom, prix) VALUES (6, 'mobilier', 'lampe', '30');

Lancer successivement ces deux scripts SQL en utilisant par exemple pgadmin.

Créer un paquetage métier sous le paquetage source.

Dans ce tutoriel nous ne créerons qu'une seule classe et qu'une seule méthode : la classe GenerateurRapportBIRT qui n'aura qu'une méthode main (le but étant seulement d'apprendre à générer des rapports depuis la DEAPI).

DesignConfig est une classe fille de la classe PlatformConfig. Comme cette dernière, elle implémente l'interface IPlatformConfig. Elle permet de spécifier la localisation des services à charger pour le lancement du moteur de conception de rapports.

//Récupération du chemin du répertoire courant

String repertoireCourant = System.getProperty("");

//Affectation du chemin vers la plateforme BIRT

String BIRT_HOME = repertoireCourant + "/runtime/ReportEngine";

//Configuration OSGi

DesignConfig config = new DesignConfig(); config.setBIRTHome(BIRT_HOME);

La classe Platform utilise le framework OSGI pour mettre à disposition les services de conception de rapports BIRT.

//Démarrage de la plateforme

Platform.startup(config);

IDesignEngine représente 'le concepteur de rapports BIRT'. Pour en récupérer une instance, il faut passer par une fabrique, 'IDesignEngineFactory'. On récupère d'abord cette fabrique via la plateforme. Cette fabrique nous permet ensuite de récupérer une instance de IDesignEngine.

//Récupération de la fabrique de 'concepteurs de rapports'

IDesignEngineFactory iDesignEngineFactory = (IDesignEngineFactory)

Platform.createFactoryObject(IDesignEngineFactory.EXTENSION_DESIGN_ENGINE_FACTORY);

//Récupération d'une instance de 'concepteur de rapport'

IDesignEngine engine = iDesignEngineFactory.createDesignEngine(config);

Cette classe représente l'état de conception c'est à dire 'une vue du travail de conception en cours'. Par exemple, dans un environnement Eclipse, elle représente la liste de tous les rapports ouverts. Il est ainsi nécessaire de récuperer une instance de la classe Session pour pouvoir concevoir des rapports. On la créé à partir de notre concepteur de rapports.

//Création d'une session de travail

SessionHandle session = engine.newSessionHandle(ULocale.FRENCH);

Une instance de ReportDesignHandle est un objet java correspondant au fichier .rptdesign représentatif d'un rapport. On l'obtient à partir d'un objet session.

//Création d'un élement rapport

ReportDesignHandle design = session.createDesign();

On passe par une fabrique d'éléments qui nous fournit des modules qu'on ajoute au fur et à mesure à notre instance de rapport.

//Création d'une fabrique de modules à insérer dans le rapport

ElementFactory factory = design.getElementFactory();

Une 'master page' représente le type de page qui va accueillir notre rapport : une page orientée texte avec tableaux, images ou bien une page orientée graphisme. On a choisi ici de ne faire que des tableaux. Aussi va-t-on utiliser la classe SimpleMasterPage. On en récupère une instance via la fabrique d'éléments.

* Création d'un élément master page

* */

//Création d'un élément Master Page

DesignElementHandle element = factory.newSimpleMasterPage("Page Master");

//Ajout de l'élément au rapport design.getMasterPages().add(element);

Il suffit de récupérer via la fabrique d'éléments une instance de la classe OdaDataSourceHandle en spécifiant bien qu'il s'agit d'une datasource de type jdbc.

* Création d'un élément source de données

* */

// Spécification des paramètres de connection

String nomDriver = "org.postgresql.Driver";

String urlBase = "jdbc:postgresql://localhost:5432/tutoriel_birt";

String loginBase = "postgres";

String passBase = "postgres";

String nomSourceDeDonnees = "table_des_produits";

// création d'un élément source de données de type jdbc

OdaDataSourceHandle dsHandle =

factory.newOdaDataSource(nomSourceDeDonnees, "");

//customisation de l'élément

dsHandle.setProperty("odaDriverClass", nomDriver);

dsHandle.setProperty("odaURL", urlBase); dsHandle.setProperty("odaUser", loginBase); dsHandle.setProperty("odaPassword", passBase);

//ajout de l'élément au rapport design.getDataSources().add(dsHandle);

Le paramètre de sélection est associé à une liste de choix (dans notre cas). Ici on choisit d'associer cette liste à un magasin de données (on aurait pu spécifier des paramètres statiques).

* Création d'un élément magasin de données (dataset)

* sur lequel se base le paramètre de sélection

* */

String nomDuDataSetPourParametreDeSelection="MagasinPourParametreDeSelection";

String requete="SELECT type_produit FROM table_des_produits group by type_produit;";

OdaDataSetHandle odaDataSetHandle =

factory.newOdaDataSet(nomDuDataSetPourParametreDeSelection,".JdbcSelectDataS

odaDataSetHandle.setDataSource(nomSourceDeDonnees);

odaDataSetHandle.setQueryText(requete);

//ajout de l'élément au rapport design.getDataSets().add(odaDataSetHandle);

On instancie le paramètre de sélection en lui associant un nom.

* Création d'un élément paramètre de sélection

* */

String nomDuParametreFiltre = "Type Produit";

ScalarParameterHandle scalarParameterHandle = factory.newScalarParameter(nomDuParametreFiltre);

Un paramètre de sélection peut présenter quatre types de choix :

- Text Box : l'utilisateur doit rentrer une valeur qu'il saisit au clavier

- Combo Box : il s'agit d'un choix entre une 'List Box' ou une 'Text Box' c'est à dire que l'utilisateur peut choisir entreune liste de valeurs ou bien peut rentrer la valeur à la main.

- List Box : il s'agit d'une liste de choix dans laquelle l'utilisateur doit choisir une ou plusieurs valeurs.

- Radio Button : l'utilisateur doit choisir une valeur dans une liste de type 'radio'.Ici on va créer une 'List Box'.

//choix du type de choix d'affichage (ici liste-box) scalarParameterHandle.setControlType(DesignChoiceConstants.PARAM_CONTROL_LIST_BOX);

Un paramètre de sélection ( de type 'List Box' ou 'Combo Box') repose sur deux types de sources :

- statique : les valeurs possibles que l'utilisateur peut choisir reposent sur un jeu de valeurs figé (ces valeurs sont

'statiques')

- dynamique : les valeurs possibles que l'utilisateur peut choisir reposent sur un jeu de valeurs non figé (ces valeursreposent sur un magasin de données sur lequel est fait un appel dynamique) Ici on va créer un paramètre de sélection de type dynamique.

//choix du type de valeurs (dynamique ici) scalarParameterHandle.setValueType(DesignChoiceConstants.PARAM_VALUE_TYPE_DYNAMIC);

Un paramètre de sélection autorise deux volumes de sélection :

- un volume unitaire : on ne peut choisir qu'une seule valeur

- un volume multiple : on peut choisir plusieurs valeurs

Ici on va choisir un paramètre de sélection avec volume unitaire.

//choix du volume de sélection possible (ici volume unitaire) scalarParameterHandle.setParamType(DesignChoiceConstants.SCALAR_PARAM_TYPE_SIMPLE);

Les types de données que peut contenir un paramètre de sélection sont de huit types différents : - de type 'Boolean'

- de type 'Date'

- de type 'DateTime'

- de type 'Decimal'

- de type 'Float'

- de type 'Integer'

- de type 'String'

- de type 'Integer'

Ici on va choisir un paramètre de sélection avec des données de type 'String'.

//choix du type des données contenues dans le paramètre scalarParameterHandle.setDataType(DesignChoiceConstants.PARAM_TYPE_STRING);

Le reste du paramétrage reste assez intuitif (voir ci-dessous).

//texte à afficher dans la fenêtre

String textePourAffichage = "Choisir le type";

scalarParameterHandle.setPromptText(textePourAffichage);

//Spécification que la valeur choisie doit être contenue dans la List-Box

scalarParameterHandle.setMustMatch(true);

//Spécification que l'affichage doit être fait de la même manière que dans la source de données du paramètre de sé

scalarParameterHandle.setFixedOrder(true);

//Spécification de la non présentation de doublon dans la liste de choix

scalarParameterHandle.setDistinct(true);

//affectation du dataset pour obtenir la liste des paramètres d'affichage scalarParameterHandle.setDataSetName(nomDuDataSetPourParametreDeSelection);

//Spécification de la valeur d'affichage de la source associée à la séléction

scalarParameterHandle.setValueExpr("dataSetRow[\"type_produit\"]");

//Spécification du libellé d'affichage de la source associée à la séléction scalarParameterHandle.setLabelExpr("dataSetRow[\"type_produit\"]");

//Pas de formatage de la valeur

scalarParameterHandle.setCategory("Unformatted");

//Ajout du paramètre au rapport design.getParameters().add(scalarParameterHandle);

Le magasin de données principal est rendu dynamique : on ne ramène que les données spécifiées par le paramètre de sélection (on aurait pu ramener toutes les données et ensuite appliquer un filtre de tri par l'intermédiaire du paramètre).

* Construction du magasin de données principal

* */

String nomDuDataSetPrincipal="DataSetPrincipal";

String

requetePrincipal="SELECT id, type_produit, nom, prix FROM table_des_produits where type_produit=?";

OdaDataSetHandle odaDataSetHandlePrincipal =

factory.newOdaDataSet(nomDuDataSetPrincipal,".JdbcSelectDataSet");

odaDataSetHandlePrincipal.setDataSource(nomSourceDeDonnees); odaDataSetHandlePrincipal.setQueryText(requetePrincipal);

//affectation du report parameter

PropertyHandle propertyHandle =

odaDataSetHandlePrincipal.getPropertyHandle(OdaDataSetHandle.PARAMETERS_PROP);

OdaDataSetParameter odaDataSetParameter = StructureFactory.createOdaDataSetParameter();

odaDataSetParameter.setName("param1");

odaDataSetParameter.setDataType(DesignChoiceConstants.PARAM_TYPE_STRING);

odaDataSetParameter.setPosition(1); odaDataSetParameter.setIsInput(true); odaDataSetParameter.setIsOutput(false);

odaDataSetParameter.setParamName(nomDuParametreFiltre);

propertyHandle.addItem(odaDataSetParameter);

//ajout de l'élément au rapport

design.getDataSets().add(odaDataSetHandlePrincipal);

La construction du Layout est assez intuitive également.

Trois grandes étapes sont à distinguer :

- association des colonnes aux valeurs

- formatage de la première ligne

- formatage de la ligne courante

* Construction de la mise en forme (Layout)

* */

CellHandle cell;

HashMap <String, String > mappingNomColonneLibelle = new HashMap< String, String>();

("id", "Identifiant");

("type_produit", "Type de Produit");

("nom", "Nom du produit"); ("prix", "Prix du produit");

TableHandle tableHandle = factory.newTableItem("Tableau Test",());

tableHandle.setWidth("100%"); tableHandle.setDataSet(design.findDataSet(nomDuDataSetPrincipal)); // Préparation du mapping données-valeurs.

PropertyHandle computedSet = tableHandle.getColumnBindings();

ComputedColumn cs1 = null;

Set<String> listeColonne = mappingNomColonneLibelle.keySet(); Iterator<String> iterateurListeColonne = listeColonne.iterator();

String valeur;

String libelle;

while (iterateurListeColonne.hasNext()) { valeur = (); libelle = (valeur); cs1 = StructureFactory.createComputedColumn();

cs1.setName(valeur);

cs1.setExpression("dataSetRow[\"" + valeur + "\"]");

computedSet.addItem(cs1); }

StyleHandle styleHandle;

// table header (libellés)

RowHandle tableHeader = (RowHandle) tableHandle.getHeader().get(0);

int i = -1;

iterateurListeColonne = listeColonne.iterator(); while (iterateurListeColonne.hasNext()) {

i = i + 1;

valeur = (); libelle = (valeur); LabelHandle label1 = factory.newLabel(valeur);

label1.setText(libelle);

cell = (CellHandle) tableHeader.getCells().get(i); cell.getContent().add(label1);

// formatage du css

styleHandle = cell.getPrivateStyle();

ColorHandle colorHandle = styleHandle.getBackgroundColor();

colorHandle.setValue("gray");

styleHandle.setTextAlign(DesignChoiceConstants.TEXT_ALIGN_CENTER); styleHandle.setVerticalAlign(DesignChoiceConstants.VERTICAL_ALIGN_MIDDLE); styleHandle.setBorderBottomStyle(DesignChoiceConstants.LINE_STYLE_SOLID); styleHandle.setBorderTopStyle(DesignChoiceConstants.LINE_STYLE_SOLID); styleHandle.setBorderRightStyle(DesignChoiceConstants.LINE_STYLE_SOLID); styleHandle.setBorderLeftStyle(DesignChoiceConstants.LINE_STYLE_SOLID); }

// table detail (valeurs)

RowHandle tableDetail = (RowHandle) tableHandle.getDetail().get(0);

i = -1;

iterateurListeColonne = listeColonne.iterator(); while (iterateurListeColonne.hasNext()) {

i = i + 1;

valeur = ();

cell = (CellHandle) tableDetail.getCells().get(i); DataItemHandle data = factory.newDataItem(valeur);

data.setResultSetColumn(valeur); cell.getContent().add(data);

// formatage du css

styleHandle = cell.getPrivateStyle();

styleHandle.setTextAlign(DesignChoiceConstants.TEXT_ALIGN_CENTER); styleHandle.setBorderBottomStyle(DesignChoiceConstants.LINE_STYLE_SOLID); styleHandle.setBorderTopStyle(DesignChoiceConstants.LINE_STYLE_SOLID); styleHandle.setBorderRightStyle(DesignChoiceConstants.LINE_STYLE_SOLID); styleHandle.setBorderLeftStyle(DesignChoiceConstants.LINE_STYLE_SOLID); }

// On ajoute finalement l'élément mise en forme

design.getBody().add(tableHandle);

//On sauvegarde finalement le rapport

String cheminRapport=repertoireCourant+"/reports/testBIRT.rptdesign";

design.saveAs(cheminRapport); design.close();

//Arrêt de la plateforme

Platform.shutdown();

Lancer le script. Vérifier l'existence du fichier 'testBIRT.rptdesign'. Ouvrir ce fichier dans la perspective 'report design' d'Eclipse. Lancer un preview afin de vérifier que le rapport a le fonctionnement attendu (voir copie d'écran ci-dessous).

Fenêtre du paramètre de sélection

Rapport

Ici a été présenté une ébauche de ce que peut faire la DEAPI. Cette API offre néanmoins encore de nombreuses possibilités notamment en utilisant d'autres types de datasource : les scripted data source, les fichiers plats, les sources de données xml ou encore les web services. Par ailleurs, la DEAPI peut également être utilisée pour modifier des rapports existants ou pour assembler différents rapports et ainsi simuler les sous-rapports. La maîtrise de la REAPI est ensuite l'étape indispensable pour implémenter BIRT dans son application web.

Enfin, merci à BiM, Bruno2r et Fleur pour l'aide fourni pour la mise en place de ce tutoriel :).