If you put the bin dir on the seach path, just type
jasperstarter
to invoke the program.
If not, you can use an absolute path. On Linux:
/opt/jasperstarter/bin/jasperstarter
and on Windows:
C:\App\jasperstarter\bin\jasperstarter.exe
if you followed the example in the install section.
If you have any problem with the binary or shell script or you need to specify some extra options to your java vm, you can invoke the program directly:
$ java -jar /opt/jasperstarter/lib/jasperstarter.jar´
or
$ java -cp /opt/jasperstarter/lib/jasperstarter.jar de.cenote.jasperstarter.App
JasperReports know three types of files:
This file is an xml file that defines the report, You can create it by hand but usually you will use one of the nice available GUI tools.
This file is the result of compiling an .jrxml file.
This file is the result of running a report. The data which is retrieved from the defined datasource is filled in the compiled report and can be stored in a .jrprint file.
JasperStarter has some global options and commands. Every command can have it's own options.
You can get an overview if you invoke jasperstarter with -h which shows you the global options and the available commands.
$ 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_params (params,lpa) - list parameters from given report
Every command has it's own help which can be invoked with <command> -h.
The command compile is for compiling one report or all reports in a directory. cp is an alias for compile.
$ jasperstarter cp -h usage: jasperstarter compile [-h] -i <file> [-o <file>] optional arguments: -h, --help show this help message and exit options: -i <file> input file (.jrxml) or directory -o <file> directory or basename of outputfile(s)
The command process is for processing a report. Thant means viewing, printing or exporting. pr is an alias for process.
$ jasperstarter pr -h usage: jasperstarter process [-h] -f <fmt> [<fmt> ...] -i <file> [-o <file>] [-w] [-a [<filter>]] [-P <p> [<p> ...]] [-r [<file>]] [-t <dbtype>] [-H <dbhost>] [-u <dbuser>] [-p <dbpasswd>] [-n <dbname>] [--db-sid <sid>] [--db-port <port>] [--db-driver <name>] [--db-url <jdbcUrl>] [--jdbc-dir <dir>] [-N <printername>] [-d] [-s <reportname>] optional arguments: -h, --help show this help message and exit options: -f <fmt> [<fmt> ...] view, print, pdf, rtf, xls, xlsx, docx, odt, ods, pptx, csv, html, xhtml, xml, jrprint -i <file> input file (.jrxml|.jasper|.jrprint) -o <file> directory or basename of outputfile(s) compile options: -w, --write-jasper write .jasper file to imput dir if jrxml is prcessed fill options: -a [<filter>] ask for report parameters. Filter: a, ae, u, ue, p, pe (see usage) -P <p> [<p> ...] report parameter: name=type:value [...] | types: string, int, double, date, image, locale -r [<file>] path to report resource dir or jar file. If <file> is not given the input directory is used. db options: -t <dbtype> database type: none, mysql, postgres, oracle, generic -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 print options: -N <printername> name of printer -d show print dialog when printing -s <reportname> set internal report/document name when printing
The command list_printers has no options. It lists the available printers on your system which can be used with optin -N of the command process. printers,lpr are aliases for list_printers.
The command list_parameters lists all user defined parameters of a given report. params,lpa are aliases for list_parameters.
$ jasperstarter params -h usage: jasperstarter list_parameters [-h] -i <file> optional arguments: -h, --help show this help message and exit options: -i <file> input file (.jrxml) or (.jasper)
The columns have the following meaning:
Example output:
$ jasperstarter params -i myreport.jasper P background java.awt.Image Background image P MyName java.lang.String Title of some component P MyDate java.util.Date
Every command, option or argument JasperStarter accepts can be stored in a file that can be additionally provided with the @ sign.
The file should contain one command/option/argument per line.
Example file (db.conf):
-t mysql -H localhost -n mydb -u volker
Example invocation with command file:
$ jasperstarter pr -f view -i myreport @db.conf
Attention! The command file should not contain any empty lines and just one linebreak with no spaces at the end of the file!
To process a report you must provide the process command pr which needs the following options:
connection information.
All other options are optional.
For output -o see section "File Handling".
The minimum options needed, to process a report with an empty datasource:
$ jasperstarter pr -i myreport.jasper -f view -t none
The minimum options required to process a report that needs a database connection:
$ jasperstarter pr -i myreport.jasper -f pdf -t mysql -H localhost -n mydb -u appuser
You can fill a report at one time and view, print or export it at a later time.
Just fill one report:
$ jasperstarter pr -i myreport.jasper -f jrprint -t mysql -H localhost -n mydb -u appuser
View a previously filled report:
$ jasperstarter pr -i myreport.jrprint -f view
Report parameters can consist of several types. Most types are self-explanatory. JasperStarter supports the following types:
Multiple parameters can be separated by spaces. A parameter has the following form:
Replace name with the parameter name in your report. Parameter names are case sensitive !
The parameter type date accepts a date in ISO format in the form: YYYY-MM-DD
The parameter type locale may consist just of the two-letter ISO-639 language code or a combination of the two-letter ISO-639 language code and the two-letter ISO-3166 country code connected by an underscore. For example de or de_DE.
$ jasperstarter pr -t mysql -u myuser -f pdf -H myhost -n mydb -i report.jasper \ -o report -p secret -P CustomerNo=int:10 StartFrom=date:2012-10-01
A simple way of customizing a report is to provide a logo or background image as parameter. In the following example we use background as parameter name for the image:
Now you can process your report with JasperStarter:
$ jasperstarter pr -t mysql -u myuser -f pdf -H myhost -n mydb -i report.jasper \ -o report -p secret -P background=image:/tmp/mybackgroundimage.jpg
Particularly windows users may need to work with spaces in file names. There are two ways you can do that. Just quote the value:
c:\jasperstarter pr -t mysql -u myuser -f pdf -H myhost -n mydb -i report.jasper \ -o report -p secret -P background=image:"C:\Temp Files\My Image.jpg" otherValue=int:1
or quote the whole parameter:
c:\jasperstarter pr -t mysql -u myuser -f pdf -H myhost -n mydb -i report.jasper \ -o report -p secret -P "background=image:C:\Temp Files\My Image.jpg" otherValue=int:1
JasperStarter can ask for parameter input with option -a.
Every parameter defined in the report can be displayed but only those are supported for input, that have a type (class) with a constructor that takes one string as an argument. Additionally special handlers for java.util.Date and java.awt.Image are provided.
It is possible to filter the displayed parameters with the following optional arguments:
In the following examples we assume a non database report which has two parameters:
The user will be prompted for the two parameters:
$ jasperstarter pr -i myreport.jasper -f view -a
The user will be prompted for the two parameters. The MyDate parameter is already filled but the user can change it:
$ jasperstarter pr -i myreport.jasper -f view -P MyDate=date:2013-01-30 -a
The user will be prompted only for the empty MyText parameter. The MyDate parameter is already filled and not displayed:
$ jasperstarter pr -i myreport.jasper -f view -P MyDate=date:2013-01-30 -a pe
Reports can use several resources like i18n resource bundles, icons or images.
If a resource exists in the same directory as the report file just specify -r without any arguments:
$ jasperstarter pr -i myreport.jasper -f view -r
If the resource is located in another directory or in a jar file the path can be given as an argument:
$ jasperstarter pr -i myreport.jasper -f view -r myresources/
or
$ jasperstarter pr -i myreport.jasper -f view -r myresources.jar
If the input file (option -i ) is not found, .jasper is added to the filename first, if the file is still not found .jrxml is added to the filename. So you can omit the file extension.
If the .jrxml file is used, it will be compiled in memory and used for further processing except you provide option -w which causes the compiled report to be written to the input directory.
A .jrprint file can be used as input but must specified with full filename.
If the output file or directory ( option -o ) is omitted, parent of the input file is used as output directory and the basename of the input file is used for as output filename:
(...) -f pdf odt -i myreports/report1
or
(...) -f pdf odt -i myreports/report1.jasper
or
(...) -f pdf odt -i myreports/report1.jrxml
results in:
myreports/report1.odt myreports/report1.pdf
If output is an existing directory, basename of input is used as filename in that directory:
(...) -f pdf odt -i myreports/report1.jasper -o month01/
results in:
month01/report1.odt month01/report1.pdf
If output is NOT an existing directory, its name is used as basename for filenames:
(...) -f pdf odt -i myreports/report1.jasper -o month01/journal.xyz
results in:
month01/journal.xyz.odt month01/journal.xyz.pdf