BIRT Reporting with Spring Boot

1. Bemutatkozás

Ebben az oktatóanyagban integrálni fogjuk a BIRT-t (Business Intelligence and Reporting Tools) a Spring Boot MVC-be, statikus és dinamikus jelentések HTML és PDF formátumban történő kiszolgálására.

2. Mi az BIRT?

A BIRT egy nyílt forráskódú motor az adatok megjelenítésének létrehozására amelyek integrálhatók a Java webalkalmazásokba.

Ez az Eclipse Foundation egyik legfelső szintű szoftverprojektje, amely az IBM és az Innovent Solutions hozzájárulását használja fel. Az Actuate indította és támogatta 2004 végén.

A keretrendszer lehetővé teszi az adatforrások széles körével integrált jelentések készítését.

3. Maven-függőségek

A BIRT-nek két fő összetevője van: egy vizuális jelentés-tervező a jelentés-tervezési fájlok létrehozásához, és egy futásidejű komponens a tervek értelmezéséhez és megjelenítéséhez.

Példa webes alkalmazásunkban mindkettőt a Spring Boot tetején fogjuk használni.

3.1. BIRT keretrendszer-függőségek

Ahogy a függőségkezelésben szoktunk gondolkodni, az első választás a BIRT keresése lenne a Maven Central-ban.

Azonban, az alapkönyvtár legújabb hivatalos verziója 2016-tól 4,6, míg az Eclipse letöltési oldalán találunk linkeket legalább két újabb verzióhoz (az áram 4,8).

Ha a hivatalos összeállítás mellett döntünk, akkor a kód legegyszerűbb módja a BIRT Report Engine csomag letöltése, amely egy teljes webes alkalmazás, amely a tanuláshoz is hasznos. Ezután le kell másolnunk azt lib mappát a projektünkbe (kb. 68 MB méretű), és mondja meg az IDE-nek, hogy az összes edényt tegye bele.

Magától értetődik, hogy ezt a megközelítést alkalmazva csak az IDE-n keresztül tudunk fordítani, mivel a Maven csak akkor találja meg ezeket az üvegeket, ha manuálisan konfiguráljuk és telepítjük őket (több mint 100 fájl!) a helyi repóban.

Szerencsére, Az Innovent Solutions úgy döntött, hogy kezébe veszi az ügyeket, és a Maven Central-on közzétette saját építményeit a legújabb BIRT-függőségek közül, ami nagyszerű, mivel kezeli számunkra az összes szükséges függőséget.

Az online fórumokon olvasható megjegyzéseket áttekintve nem világos, hogy ezek a műtárgyak készen állnak-e a gyártásra, de az Innovent Solutions a kezdetektől fogva az Eclipse csapata mellett dolgozott a projekten, így projektünk ezekre támaszkodik.

A BIRT felvétele most nagyon egyszerű:

 com.innoventsolutions.birt.runtime org.eclipse.birt.runtime_4.8.0-20180626 4.8.0 

3.2. Tavaszi csomagtartó függőségek

Most, hogy a BIRT-t importáltuk a projektünkbe, hozzá kell adnunk a standard Spring Boot függőségeket a pom fájlunkba.

Van azonban egy buktató, mert a BIRT jar tartalmazza a saját megvalósítását Slf4J, ami nem játszik jól Vissza és az indítás során konfliktuskivételt dob.

Mivel nem tudjuk eltávolítani az üvegből, a probléma megoldása érdekében ki kell zárnunk a Visszaadást:

 org.springframework.boot spring-boot-starter-logging ch.qos.logback logback-classic 

Most végre készen állunk az indulásra!

4. BIRT jelentések

A BIRT keretében a jelentés egy hosszú XML konfigurációs fájl, amelyet a kiterjesztés azonosít rptdesign.

Megmondja a Motornak, hogy mit és hova kell rajzolni, a cím stílusától kezdve az adatforráshoz való csatlakozáshoz szükséges tulajdonságokig.

Az alapvető dinamikus jelentéshez három dolgot kell konfigurálnunk:

  1. az adatforrás (példánkban helyi CSV fájlt használunk, de könnyen lehet egy adatbázis tábla)
  2. a megjeleníteni kívánt elemek (diagramok, táblázatok stb.)
  3. az oldal kialakítása

A jelentés HTML-oldalaként van felépítve, fejléccel, törzszel, lábléccel, szkriptekkel és stílusokkal.

A keretrendszer kiterjedt alkatrészkészletet kínál, amelyek közül a dobozból kiválaszthatók, beleértve az integrációt a mainstream adatforrásokba, elrendezésekbe, diagramokba és táblázatokba. És kibővíthetjük a sajátunk hozzáadásával!

A jelentésfájl előállításának két módja van: vizuális vagy programszerű.

5. Az Eclipse jelentés tervezője

A jelentések készítésének megkönnyítése érdekében az Eclipse csapata elkészített egy jelentéstervező eszközt plugin a népszerű IDE-hez.

Ez az eszköz egy egyszerű drag & drop felületet tartalmaz tól Paletta a bal oldalon, amely automatikusan megnyitja az oldalhoz hozzáadott új komponens beállítási ablakát. Megtekinthetjük az egyes komponensek összes rendelkezésre álló testreszabását is, ha rákattintunk az oldalon, majd a Tulajdonságszerkesztő gombra (az alábbi képen kiemelve).

A teljes oldalszerkezet fanézetben való megjelenítéséhez csak a gombra kell kattintanunk Vázlat gomb.

A Data Explorer fül a jelentésünkhöz meghatározott adatforrásokat is tartalmazza:

A képen megjelenített jelentésminta megtalálható az elérési útvonalon /reports/csv_data_report.rptdesign

A vizuális tervező további előnye az online dokumentáció, amely a programozási megközelítés helyett inkább erre az eszközre koncentrál.

Ha már használjuk az Eclipse alkalmazást, akkor telepítenünk kell a BIRT Report Design plugint, amely tartalmaz egy előre definiált perspektívát és a vizuális szerkesztőt.

Azoknak a fejlesztőknek, akik jelenleg nem használják az Eclipse alkalmazást és nem akarok váltani, van egy Eclipse Report Designer csomag, amely hordozható Eclipse telepítésből áll, a BIRT beépülő modullal előre telepítve.

Miután elkészült a jelentésfájl, elmenthetjük a projektünkbe, és visszatérhetünk a kódoláshoz az általunk preferált környezetben.

6. A programozási megközelítés

Azt is megtehetjük csak kódot használva készítsen jelentést, de ez a megközelítés a rendelkezésre álló gyenge dokumentáció miatt sokkal nehezebb, ezért készüljön fel a forráskód és az online fórumok feltárására.

Érdemes megfontolni, hogy minden unalmas tervezési részletek mint a méret, a hossz és a rács pozíciója sokkal könnyebb megbirkózni a tervező használatával.

Ennek igazolásához íme egy példa arra, hogyan definiálható egy egyszerű statikus oldal képpel és szöveggel:

DesignElementHandle elem = factory.newSimpleMasterPage ("Page Master"); design.getMasterPages (). add (elem); GridHandle rács = factory.newGridItem (null, 2, 1); design.getBody (). add (rács); grid.setWidth ("100%"); RowHandle row0 = (RowHandle) rács.getRows (). Get (0); ImageHandle image = gyár.newImage (null); CellHandle cell = (CellHandle) sor0.getCells (). Get (0); cell.getContent (). add (kép); image.setURL ("\" // www.baeldung.com/wp-content/themes/baeldung/favicon/favicon-96x96.png \ ""); LabelHandle címke = factory.newLabel (null); cell = (CellHandle) sor0.getCells (). get (1); cell.getContent (). add (címke); label.setText ("Helló, Baeldung világ!");

Ez a kód egyszerű (és csúnya) jelentést generál:

A fenti képen látható jelentésminta ezen az útvonalon található: /reports/static_report.rptdesign.

Miután kódoltuk, hogyan kell kinéznie a jelentésnek és milyen adatokat kell megjelenítenie, a mi futtatásával létrehozhatjuk az XML fájlt ReportDesignApplication osztály.

7. Adatforrás csatolása

Korábban említettük, hogy a BIRT sokféle adatforrást támogat.

Példaprojektünkhöz egy egyszerű CSV fájlt használtunk, három bejegyzéssel. Megtalálható a jelentések mappa, és három egyszerű adatsorból áll, plusz fejlécekből:

Hallgató, matematika, földrajz, történelemszámla, 10,3,8 Tom, 5,6,5 Anne, 7, 4,9

7.1. Az adatforrás konfigurálása

Ha engedélyezi a BIRT-nek a fájlunk (vagy bármilyen más forrás) használatát, konfigurálnunk kell a Adatforrás.

A fájlunkhoz létrehoztunk egy Lapos fájl adatforrása a riporttervezővel néhány lépésben:

  1. Nyissa meg a tervező perspektíváját, és nézze meg a vázlat jobbra.
  2. Kattintson a jobb gombbal a Adatforrások ikon.
  3. Válassza ki a kívánt forrás típust (esetünkben a lapos fájl forrást).
  4. Most választhatunk egy teljes mappa vagy csak egy fájl betöltését. A második opciót használtuk (ha az adatfájlunk CSV formátumú, akkor mindenképpen az első sort akarjuk használni oszlopnév indikátorként).
  5. Tesztelje a kapcsolatot, hogy megbizonyosodjon arról, hogy az útvonal helyes-e.

Csatoltunk néhány képet az egyes lépések bemutatásához:

7.2. Az adatkészlet

Az adatforrás készen áll, de még meg kell határoznunk a sajátunkat Adatkészlet, amely a jelentésünkben szereplő tényleges adat:

  1. Nyissa meg a tervező perspektíváját, és nézze meg a vázlat jobbra.
  2. Kattintson a jobb gombbal a Adathalmazok ikon.
  3. Válassza ki a kívánt elemet Adatforrás és a típus (esetünkben csak egy típus létezik).
  4. A következő képernyő a kiválasztott adatforrás és adatkészlet típusától függ: esetünkben egy olyan oldalt látunk, ahol kiválaszthatjuk a felvenni kívánt oszlopokat.
  5. A beállítás befejezése után bármikor megnyithatjuk a konfigurációt, duplán kattintva az adatkészletünkre.
  6. Ban ben Kimeneti oszlopok, beállíthatjuk a megjelenített adatok megfelelő típusát.
  7. Ezután megtekinthetünk egy előnézetet a gombra kattintva Eredmények előnézete.

Ismét néhány kép a lépések tisztázásához:

7.3. Egyéb adatforrástípusok

Amint azt a Adatkészlet konfiguráció esetén a rendelkezésre álló opciók a Adatforrás hivatkozott.

CSV-fájlunkhoz a BIRT lehetőséget ad arra, hogy mely oszlopokat jelenítse meg, az adattípust, és ha a teljes fájlt be akarjuk tölteni. Másrészt, ha rendelkezünk JDBC adatforrással, előfordulhat, hogy SQL lekérdezést vagy tárolt eljárást kell írnunk.

Tól Adathalmazok menü, két vagy több adatsort is összekapcsolhatunk egy új adathalmazban.

8. A jelentés elkészítése

Miután elkészült a jelentésfájl, át kell adnunk a motornak a megjelenítéshez. Ehhez néhány dolgot végre kell hajtani.

8.1. A motor inicializálása

A ReportEngine osztály, amely értelmezi a tervfájlokat és előállítja a végeredményt, a BIRT futásidejű könyvtár része.

Egy csomó segítőt és feladatot használ a munka elvégzéséhez, ami elég erőforrásigényes:

Kép forrása: Eclipse BIRT dokumentáció

Jelentős költségekkel jár egy motorpéldány létrehozása, elsősorban a bővítmények betöltésének költségei miatt. Ebből kifolyólag, csak egyet kellene létrehoznunk ReportEngine példányt, és több jelentés futtatására használja.

A jelentésmotort a Felület. A motor létrehozása előtt el kell indítanunk a Felület, amely betölti a megfelelő plug-ineket:

A @PostConstruct védett void inicializálása () dobja a BirtException {EngineConfig config = new EngineConfig (); config.getAppContext (). put ("tavasz", ez. kontextus); Platform.startup (config); IReportEngineFactory factory = (IReportEngineFactory) Platform .createFactoryObject (IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY); birtEngine = gyár.createReportEngine (config); imageFolder = System.getProperty ("user.dir") + File.separatorChar + reportsPath + imagesPath; loadReports (); }

Amikor már nincs rá szükségünk, elpusztíthatjuk:

@A nyilvános érvénytelenítés megsemmisítése megsemmisítés () {birtEngine.destroy (); Platform.leállítás (); }

8.2. A kimeneti formátum megvalósítása

A BIRT már több kimeneti formátumot támogat:HTML, PDF, PPT és ODT, hogy csak néhányat említsünk.

A mintaprojekthez kettőt megvalósítottunk a módszerekkel generatorPDFReport és generálHTMLReport.

Ezek kissé eltérnek a szükséges speciális tulajdonságoktól, például a kimeneti formátumtól és a képkezelőktől függően.

Valójában a PDF-ek beágyazzák a képeket a szöveggel együtt, míg a HTML-jelentéseknek azokat generálniuk és / vagy összekapcsolniuk kell.

Így, a PDF-megjelenítési funkció meglehetősen egyszerű:

private void generálPDFReport (IReportRunnable jelentés, HttpServletResponse válasz, HttpServletRequest kérés) {IRunAndRenderTask runAndRenderTask = birtEngine.createRunAndRenderTask (jelentés); response.setContentType (birtEngine.getMIMEType ("pdf")); IRenderOption opciók = new RenderOption (); PDFRenderOption pdfRenderOption = új PDFRenderOption (opciók); pdfRenderOption.setOutputFormat ("pdf"); runAndRenderTask.setRenderOption (pdfRenderOption); runAndRenderTask.getAppContext (). put (EngineConstants.APPCONTEXT_PDF_RENDER_CONTEXT, kérelem); próbáld ki a {pdfRenderOption.setOutputStream (response.getOutputStream ()) parancsot; runAndRenderTask.run (); } catch (e kivétel) {dobjon új RuntimeException (e.getMessage (), e); } végül {runAndRenderTask.close (); }}

Míg a HTML-megjelenítési funkciónak további beállításokra van szüksége:

private void generálóHTMLReport (IReportRunnable jelentés, HttpServletResponse válasz, HttpServletRequest kérés) {IRunAndRenderTask runAndRenderTask = birtEngine.createRunAndRenderTask (jelentés); response.setContentType (birtEngine.getMIMEType ("html")); IRenderOption opciók = new RenderOption (); HTMLRenderOption htmlOptions = új HTMLRenderOption (opciók); htmlOptions.setOutputFormat ("html"); htmlOptions.setBaseImageURL ("/" + reportsPath + imagesPath); htmlOptions.setImageDirectory (imageFolder); htmlOptions.setImageHandler (htmlImageHandler); runAndRenderTask.setRenderOption (htmlOptions); runAndRenderTask.getAppContext (). put (EngineConstants.APPCONTEXT_BIRT_VIEWER_HTTPSERVET_REQUEST, kérelem); próbáld ki a {htmlOptions.setOutputStream (response.getOutputStream ()) parancsot; runAndRenderTask.run (); } catch (e kivétel) {dobjon új RuntimeException (e.getMessage (), e); } végül {runAndRenderTask.close (); }}

A figyelemre méltó, beállítottuk a HTMLServerImageHandler ahelyett, hogy elhagyná az alapértelmezett kezelőt. Ez a kis különbség nagy hatással van a létrehozottra img címke:

  • az alapértelmezett kezelő összekapcsolja a img címke a fájlrendszer elérési útjára, sok böngésző biztonsági okokból letiltotta
  • a HTMLServerImageHandler hivatkozások a szerver URL-jére

A ... val setImageDirectory módszerrel megadjuk, hogy a motor hova menti a létrehozott képfájlt.

Alapértelmezés szerint a kezelő minden kérésre új fájlt generál, tehát hozzáadhatunk egy gyorsítótár-réteget vagy egy törlési házirendet.

8.3. A képek közzététele

HTML jelentés esetén a képfájlok külsőek, ezért hozzáférhetőnek kell lenniük a kiszolgáló elérési útján.

A fenti kódban a setBaseImageURL módszerrel elmondjuk a motornak, hogy milyen relatív utat kell használni a img tag link, ezért meg kell győződnünk arról, hogy az út valóban elérhető-e!

Emiatt a mi ReportEngineApplication, úgy konfiguráltuk a Spring-et, hogy közzétegye a képek mappa:

@SpringBootApplication @EnableWebMvc nyilvános osztály A ReportEngineApplication a WebMvcConfigurer {@Value ("$ {reports.relative.path}") privát karakterlánc-jelentéseketPath; @Value ("$ {images.relative.path}") privát karakterlánc imagesPath; ... @Orride public void addResourceHandlers (ResourceHandlerRegistry registry) {register .addResourceHandler (reportsPath + imagesPath + "/ **") .addResourceLocations ("file: ///" + System.getProperty ("user.dir") + " / "+ reportsPath + imagesPath); }}

Bármilyen utat is választunk, meg kell győződnünk arról, hogy ugyanazt az utat használják itt és a htmlOptions az előző részletből, különben jelentésünk nem képes képeket megjeleníteni.

9. A jelentés megjelenítése

Az alkalmazás elkészítéséhez az utolsó komponens a Vezérlő a renderelt eredmény visszaadásához:

@RequestMapping (metódus = RequestMethod.GET, value = "/ report / {name}") @ResponseBody public void generateFullReport (HttpServletResponse válasz, HttpServletRequest kérés, @PathVariable ("név") String neve, @RequestParam ("output") output) dobja a EngineException, IOException {OutputType format = OutputType.from (output); reportService.generateMainReport (név, formátum, válasz, kérés); }

A ... val Kimenet paramétert, hagyhatjuk, hogy a felhasználó kiválassza a kívánt formátumot - HTML vagy PDF.

10. A jelentés tesztelése

A. Futtatásával elindíthatjuk az alkalmazást ReportEngineApplication osztály.

Az indítás során a BirtReportService osztály betölti az összes, a / jelentések mappába.

Jelentéseink működésének megtekintéséhez a böngészőnkre kell mutatnunk:

  • / report / csv_data_report? output = pdf
  • / report / csv_data_report? output = html
  • / report / static_report? output = pdf
  • / report / static_report? output = html

Itt van, hogyan csv_data_report a jelentés úgy néz ki:

Egy jelentés újratöltéséhez a tervfájl módosítása után csak a böngészőnkre mutatunk / report / reload.

11. Következtetés

Ebben a cikkben integráltuk a BIRT-et a Spring Boot-ba, feltárva a buktatókat és kihívásokat, valamint annak erejét és rugalmasságát.

A cikk forráskódja elérhető a GitHubon.