Built by Maven

Použití

Instalace

Uživatelé Windows

Rozbalte distribuční archiv do složky, kterou jste si vybrali, např.:

C:\App\jasperstarter

Přidejte složku

C:\App\jasperstarter\bin

do uživatelské či systémové proměnné PATH.

nebo prostě použijte setup.exe

Linuxoví uživatelé

Extrahujte distribuční archiv do složky, kterou jste si vybrali, např.:

/opt/jasperstarter

Přidejte složku

/opt/jasperstarter/bin

do uživatelské či systémové proměnné PATH.

Vyvolání JasperStarteru

Pokud jste přidali složku bin do proměnné PATH, stačí pro vyvolání programu zadat

$ jasperstarter

Pokud ne, můžete zadat absolutní cestu. V Linuxu:

/opt/jasperstarter/bin/jasperstarter

a ve Windows:

C:\App\jasperstarter\bin\jasperstarter.exe

pokud jste se řídili příkladem v kapitole instalace.

Pokud máte problém s binárním souborem nebo s shell skriptem nebo pokud potřebujete pro java VM specifikovat jiné volby, vyvolejte program přímo:

$ java -jar /opt/jasperstarter/lib/jasperstarter.jar

nebo

$ java -cp /opt/jasperstarter/lib/jasperstarter.jar de.cenote.jasperstarter.App

Koncepty

JasperReport soubory

JasperReports zná tři typy souborů:

  • Soubor definující report myreport.jrxml

    Jedná se o xml soubor, který definuje report. Můžete si je napsat ručně, ale spíš použijete jeden z těch hezkých dostupných GUI nástrojů.

  • Soubor zkompilovaného reportu myreport.jasper

    Tento soubor je výsledkem kompilování souboru .jrxml.

  • Soubor reportu s daty myreport.jrprint

    Tento soubor získáte po vyvolání reportu. Data získaná z požadovaného datového zdroje vyplní kompilovaný report a výsledek je možné uložit jako .jrprint soubor.

Stádia zpracování

Zpracování reportu probíhá ve třech fázích:

  • kompilování vytvoří soubor .jasper
  • vyplnění může být volitelně uloženo jako soubor .jrprint
  • náhled, tisk nebo export do jednoho nebo více podporovaných formátů

JasperStarter umí provést všechny najednou v jednom příkazu.

JasperStarter příkazy a volby

JasperStarter obsahuje několik globálních příkazů a voleb. Každý příkaz může mít vlastní volby.

Přehled získáte vyvoláním jasperstarter s -h, které vám ukáže všechny globální volby a příkazy, které máte k dispozici.

$ jasperstarter -h
usage: jasperstarter [-h] [--locale <lang>] [-v] [-V] <cmd> ...

optional arguments:
  -h, --help             show this help message and exit
  --locale <lang>        set locale  with  two-letter  ISO-639  code  or  a
                         combination of ISO-639 and ISO-3166 like de_DE
  -v, --verbose          display additional messages
  -V, --version          display version information and exit

commands:
  <cmd>                  type <cmd> -h to get help on command
    compile (cp)         compile reports
    process (pr)         view, print or export an existing report
    list_printers (printers,lpr)
                         lists available printers
    list_parameters (params,lpa)
                         list parameters from a given report

Každý příkaz má také vlastní nápovědu, kterou lze vyvolat pomocí <command> -h.

Příkaz compile (cp)

Příkaz compile slouží ke kompilování jednoho nebo všech reportů v adresáři. cp je alias pro compile.

$ jasperstarter cp -h
usage: jasperstarter compile [-h] [-o <output>] <input>

optional arguments:
  -h, --help             show this help message and exit

options:
  <input>                input file (.jrxml) or directory
  -o <output>            directory or basename of outputfile(s)

Příkaz process (pr)

Příkaz process slouží ke zpracování jednoho reportu. Může to být náhled, tisk nebo export. pr je alias pro process.

$ jasperstarter pr -h
usage: jasperstarter process [-h] -f <fmt> [<fmt> ...] [-o <output>] [-w]
                     [-a [<filter>]] [-P <param> [<param> ...]]
                     [-r [<resource>]] [-t <dstype>] [-H <dbhost>]
                     [-u <dbuser>] [-p <dbpasswd>] [-n <dbname>]
                     [--db-sid <sid>] [--db-port <port>]
                     [--db-driver <name>] [--db-url <jdbcUrl>]
                     [--jdbc-dir <dir>] [--data-file <file>]
                     [--csv-first-row] [--csv-columns <list>]
                     [--csv-record-del <delimiter>]
                     [--csv-field-del <delimiter>]
                     [--csv-charset <charset>] [--xml-xpath <xpath>]
                     [--json-query <jsonquery>]
                     [--jsonql-query <jsonqlquery>] [-N <printername>] [-d]
                     [-s <reportname>] [-c <copies>]
                     [--out-field-del <delimiter>]
                     [--out-charset <charset>] <input>

optional arguments:
  -h, --help             show this help message and exit

options:
  -f <fmt> [<fmt> ...]   view, print, pdf, rtf,  xls,  xlsMeta, xlsx, docx,
                         odt, ods, pptx,  csv,  csvMeta,  html, xhtml, xml,
                         jrprint
  <input>                input file (.jrxml|.jasper|.jrprint)
  -o <output>            directory or basename  of  outputfile(s),  use '-'
                         for stdout

compile options:
  -w, --write-jasper     write .jasper  file  to  input  dir  if  jrxml  is
                         processed

fill options:
  -a [<filter>]          ask for report parameters.  Filter:  a, ae, u, ue,
                         p, pe (see usage)
  -P <param> [<param> ...]
                         report parameter: name=value [...]
  -r [<resource>]        path to  report  resource  dir  or  jar  file.  If
                         <resource> is not  given  the  input  directory is
                         used.

datasource options:
  -t <dstype>            datasource type:  none,  csv,  xml,  json, jsonql,
                         mysql, postgres, oracle, generic (jdbc)
  -H <dbhost>            database host
  -u <dbuser>            database user
  -p <dbpasswd>          database password
  -n <dbname>            database name
  --db-sid <sid>         oracle sid
  --db-port <port>       database port
  --db-driver <name>     jdbc driver class name for use with type: generic
  --db-url <jdbcUrl>     jdbc url without user, passwd with type:generic
  --jdbc-dir <dir>       directory where  jdbc  driver  jars  are  located.
                         Defaults to ./jdbc
  --data-file <file>     input file for file based  datasource, use '-' for
                         stdin
  --csv-first-row        first row contains column headers
  --csv-columns <list>   Comma separated list of column names
  --csv-record-del <delimiter>
                         CSV Record Delimiter - defaults to line.separator
  --csv-field-del <delimiter>
                         CSV Field Delimiter - defaults to ","
  --csv-charset <charset>
                         CSV charset - defaults to "utf-8"
  --xml-xpath <xpath>    XPath for XML Datasource
  --json-query <jsonquery>
                         JSON query string for JSON Datasource
  --jsonql-query <jsonqlquery>
                         JSONQL query string for JSONQL Datasource

output options:
  -N <printername>       name of printer
  -d                     show print dialog when printing
  -s <reportname>        set internal report/document name when printing
  -c <copies>            number of copies. Defaults to 1
  --out-field-del <delimiter>
                         Export CSV (Metadata)  Field  Delimiter - defaults
                         to ","
  --out-charset <charset>
                         Export CSV (Metadata) Charset  - defaults to "utf-
                         8"

Příkaz list_printers (printers,lpr)

Příkaz list_printers nemá žádné volby. Vypíše všechny tiskárny dostupné ve vašem systému, které můžete použít s volbou -N u příkazu process. printers, lpr je alias pro list_printers.

Příkaz list_parameters (params,lpa)

Příkaz list_parameterss nabídne seznam všech parametrů reportu definovaných uživatelem. params, lpa are aliases for list_parameters.

$ jasperstarter params -h
usage: jasperstarter list_parameters [-h] <input>

optional arguments:
  -h, --help             show this help message and exit

options:
  <input>                input file (.jrxml) or (.jasper)

Sloupce mají následující význam:

  • P/N - Prompt flag ano či ne
  • Název parametru
  • Typ parametru (class name)
  • Nepovinný popis

Příklad výstupu:

$ jasperstarter params myreport.jasper
P background java.awt.Image   Background image
P MyName     java.lang.String Title of some component
P MyDate     java.util.Date

Příkazové soubory

Každý příkaz, volbu nebo argument, které JasperStarter akceptuje, můžete uložit do souboru, který pak po přidání @ můžete přidat k vyvolání.

Takový soubor by měl obsahovat na jednom řádku pouze jeden příkaz/volbu/argument.

Příklad (db.conf):

-t
mysql
-H
localhost
-n
mydb
-u
volker

Příklad vyvolání s příkazovým souborem:

$ jasperstarter pr myreport -f view @db.conf

Pozor! Příkazový soubor nesmí obsahovat žádné prázdné řádky a musí být zakončen jedním zalomením řádku!

Zpracování reportů

Aby došlo ke zpracování reportu, zadejte příkaz pr, který potřebuje následující volby:

  • <input> vstupní soubor (definice reportu, kompilovaný report nebo vyplněný report).
  • -f seznam výstupních formátů oddělených mezerou.
    • view a print se navzájem vylučují, print bude ignorováno, pokud jste zadali i view.
  • -t typ databáze, pokud váš report vyžaduje spojení s databází. Default nastavení je none.
    • pokud typ databáze není none musíte specifikovat údaje potřebné pro spojení.

Všechny ostatní volby jsou nepovinné.

Pro výstup -o viz kapitola "Zacházení se soubory".

<input> je nyní pouze parametr. Na pořadí voleb a tohoto parametru nezáleží, ale parametr nelze umístit za volbu, která sama má jistý počet parametrů. Tyto volby jsou:

  • -f -a -P -r

Následující případ tedy fungovat nebude:

$ jasperstarter pr -f view myreport.jasper

Ale tento bude:

$ jasperstarter pr -f print pdf -d myreport.jasper
$ jasperstarter pr -f view -t mysql myreport.jasper -H localhost -u myuser -n mydb

The easiest way to circumvent any problems regarding arguments is to always place <input> at the first position right behind the command as shown in the following examples.

Minimální report bez databáze

Pro zpracování reportu s prázdnou databází potřebujete minimálně následující volby:

$ jasperstarter pr myreport.jasper -f view

Minimální report s databází

Pro zpracování reportu, který potřebuje připojení k databázi, musíte zadat minimálně následující volby:

$ jasperstarter pr myreport.jasper -f pdf -t mysql -H localhost -n mydb -u appuser

Náhled, tisk nebo export již vyplněných reportů

Report je možné pouze vyplnit. Náhled, tisk a export je možný i později.

Pouhé vyplnění reportu:

$ jasperstarter pr myreport.jasper -f jrprint -t mysql -H localhost -n mydb -u appuser

Náhled již vyplněného reportu:

$ jasperstarter pr myreport.jrprint -f view

Reporty se zdrojem dat ve formátu CSV

Znaková sada souborů CSV je defaultně UTF-8. Další často používané znakové sady jsou cp1252 (Windows), ISO-8859-1 or ISO-8859-15 (Linux). Znakovou sadu CSV souboru lze specifikovat parametrem --csv-charset.

Jednotlivé údaje jsou obvykle odděleny novým řádkem, nemusí tak tomu ale být. separátor je závislý na defaultním separátoru celého systému a ten se v každém operačním systému liší. Pokud používáte CSV soubory z jiného systému, musíte tedy zadat správný separátor pomocí parametru --csv-record-del:

  • Windows: \r\n
  • Linux/Mac: \n

Jednotlivá pole mohou být oddělena jakýmkoliv znakem a navíc být uzavřena do například uvozovkami. Separátor pole je defaultně ,

Jednoduchý příklad:

$ jasperstarter pr csv.jrxml -f view -t csv --data-file data.csv --csv-first-row

Složitější příklad:

$ jasperstarter pr csv.jrxml -f view -t csv --data-file data.csv \
--csv-columns Name,Phone --csv-record-del="\n" --csv-field-del="|" \
--csv-charset=cp1252

Reporty s parametrem runtime

Parametry reportu se mohou skládat z více typů (classes). JasperStarter umí zacházet se všemi typy, které mají konstruktor typu String. Navíc má JasperStarter speciální funkce pro typy, které nemají konstruktor typu String nebo potřebují speciální zacházení. Jedná se o:

  • date, image, locale

Parametry s více hodnotami se oddělují mezerami. Parameter má následující formu:

  • <name>=<value>

    Míso name dosaďte název parametru ve vašem reportu. U názvů parametrů dbejte na velká a malá písmena!

    Datum je v ISO formátu a má tvar: YYYY-MM-DD Parametr typu date akceptuje datum v ISO formátu a ve tvaru YYYY-MM-DD

    Parametr typu locale může mít dvě písmena - jazykový kód ISO-639 - nebo se skládat z kódu pro jazyk (ISO-639) a z kódu pro zemi (ISO-3166) spojených podtržítkem. Například de nebo de_DE.

    $ jasperstarter pr report.jasper -t mysql -u myuser -f pdf -H myhost -n mydb \
-o report -p secret -P CustomerNo=10 StartFrom=2012-10-01
Parametry pro image

Report lze snadno upravit přidáním loga či obrázku v pozadí jako parametr. V následujícím příkladu použijeme background jako název parametru pro obrázek:

  • Vytvořte ve svém reportu nový parametr a změňte jeho vlastnosti:
    • Name = background
    • Parameter Class = java.awt.Image
  • Přidejte do reportu obrázek a změňte jeho vlastnosti:
    • Image Expression = $P{background}
    • Expression Class = java.awt.Image
  • zkompilujte report

Nyní můžete report zpracovat pomocí JasperStarteru:

$ jasperstarter pr report.jasper -t mysql -u myuser -f pdf -H myhost -n mydb \
-o report -p secret -P background=/tmp/mybackgroundimage.jpg
Zadávání parametrů, které obsahují mezery

Především uživatelé windows budou určitě muset pracovat s názvy souborů, které obsahují mezery. Existují dva způsoby. Zadejte do uvozovek buď hodnotu:

c:\jasperstarter pr report.jasper -t mysql -u myuser -f pdf -H myhost -n mydb \
-o report -p secret -P background="C:\Temp Files\My Image.jpg" otherValue=1

nebo celý parametr:

c:\jasperstarter pr report.jasper -t mysql -u myuser -f pdf -H myhost -n mydb \
-o report -p secret -P "background=C:\Temp Files\My Image.jpg" otherValue=1
Dialog pro zadávání parametrů

JasperStarter umí požádat o zadání parametrů volbou -a.

Lze zobrazit každý parametr, který je v reportu definovaný, ale zadat lze pouze takový, který má typ (class) s konstruktorem, který vyžaduje jeden string coby argumen nebo pro něj existuje extra funkce.

Je možné zúžit výběr zobrazených parametrů pomocí následujících nepovinných argumentů:

  • a - všechny parametry (včetně systémových parametrů)
  • ae - všechny prázdné parametry (parametry, pro které není na příkazovém řádku zadána žádná hodnota)
  • p - všechny parametry definované uživatelem, které byly vybrány pro zobrazení ve výběrovém dialogu (defaultní, pokud -a nemá žádné argumenty)
  • pe - všechny prázdné uživatelské parametry vybrané pro zobrazení
  • u - všechny parametry definované uživatelem
  • ue - všechny prázdné parametry definované uživatelem

V následujících příkladech se podíváme na report bez databáze, který má dva parametry:

  • MyDate (java.util.Date)
  • MyText (java.lang.String)

Uživatel bude vyzván, aby zadal tyto dva parametry:

$ jasperstarter pr myreport.jasper -f view -a

Uživatel bude vyzván, aby zadal dva parametry. Paramet MyDate již je vyplněný, lze ho ale změnit:

$ jasperstarter pr myreport.jasper -f view -P MyDate=2013-01-30 -a

Uživatel bude vyzván pouze k zadání prázdného parametru MyText. Parametr MyDate již je vyplněný a nezobrazí se:

$ jasperstarter pr myreport.jasper -f view -P MyDate=2013-01-30 -a pe

Reporty se zdroji

Reporty mohou používat několik různých zdrojů, jako třeba resource balíčky i18n, ikony či obrázky.

Pokud se zdroje nacházejí ve stejném adresáři jako report, specifikujte pouze -r bez argumentů:

$ jasperstarter pr myreport.jasper -f view -r

Pokud se zdroje nacházejí v jiném adresáři, nebo v souboru jar, můžete jako argument zadat cestu:

$ jasperstarter pr myreport.jasper -f view -r myresources/

nebo

$ jasperstarter pr myreport.jasper -f view -r myresources.jar

Zacházení se soubory

Pokud vstupní soubor (volba -i ) nebyl nalezen, je k názvu souboru přidáno nejdřív .jasper, pokud soubor opět nebyl nalezen, je k názvu souboru přidáno .jrxml. Koncovku souboru tedy můžete vynechat.

Pokud je použitý soubor .jrxml, zkompiluje se a uloží pro další zpracování. Pokud zadáte volbu -w, zkompilovaný soubor se zapíše do adresáře input.

Jako vstupní soubor můžete použít i soubor .jrprint, musíte však zadat celý název souboru.

Pokud není uveden výstupní soubor nebo adresář ( volba -o ), bude pro uložení výstupního souboru použit nadřazený adresář a základní název vstupního souboru:

(...) myreports/report1 -f pdf odt

nebo

(...) myreports/report1.jasper -f pdf odt

nebo

(...) myreports/report1.jrxml -f pdf odt

výsledek:

myreports/report1.odt
myreports/report1.pdf

Pokud existuje adresář output, základní název input poslouží pro pojmenování souboru v adresáři:

(...) myreports/report1.jasper -f pdf odt -o month01/

výsledek:

month01/report1.odt
month01/report1.pdf

Pokud adresář output neexistuje, jeho název poslouží pro pojmenování souborů:

(...) myreports/report1.jasper -f pdf odt -o month01/journal.xyz

výsledek:

month01/journal.xyz.odt
month01/journal.xyz.pdf