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_parameters (params,lpa) list parameters from a 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] [-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)
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> ...] [-o <output>] [-w] [-a [<filter>]] [-P <param> [<param> ...]] [-r [<resource>]] [-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>] [--data-file <file>] [--csv-first-row] [--csv-columns <list>] [--csv-record-del <delimiter>] [--csv-field-del <delimiter>] [--csv-charset <charset>] [--xml-xpath <xpath>] [-N <printername>] [-d] [-s <reportname>] [-c <copies>] <input> 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 <input> input file (.jrxml|.jasper|.jrprint) -o <output> 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 <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. db options: -t <dbtype> database type: none, csv, xml, 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 --data-file <file> input file for file based datasource --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 print 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
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] <input> optional arguments: -h, --help show this help message and exit options: <input> input file (.jrxml) or (.jasper)
The columns have the following meaning:
Example output:
$ 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
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 myreport -f view @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".
<input> is now just an argument. The order of options and this argument does not matter but an argument cannot be placed behind an option that takes a vague number of arguments by itself. These options are:
So the following statement will not work:
$ jasperstarter -f view myreport.jasper
But these will:
$ jasperstarter -f print pdf -d myreport.jasper $ jasperstarter -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.
The minimum options needed, to process a report with an empty datasource:
$ jasperstarter pr myreport.jasper -f view
The minimum options required to process a report that needs a database connection:
$ jasperstarter pr 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 myreport.jasper -f jrprint -t mysql -H localhost -n mydb -u appuser
View a previously filled report:
$ jasperstarter pr myreport.jrprint -f view
The CSV file charset defaults to UTF-8. Other common used charsets are cp1252 (Windows), or 5 (Linux). You can specify the csv file charset with the --csv-charset parameter.
Records are usually delimited by a newline but this is not a must. The record delimiter defaults to the system line separator which is different depending on your operating system. If you use CSV files from other systems you must provide the correct line ending with the --csv-record-del parameter:
Fields can be delimited by any char and optionally be enclosed by quotation marks. The field delimiter defaults to ,
A simple example:
$ jasperstarter pr csv.jrxml -f view -t csv --data-file data.csv --csv-first-row
A more complex example:
$ 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
Report parameters can consist of several types (classes). JasperStarter can generally handle all classes that have a constructor of type String. Additionally JasperStarter has special handlers for some classes that have no constructor of type String or otherwiese need special handling. These are:
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 report.jasper -t mysql -u myuser -f pdf -H myhost -n mydb \ -o report -p secret -P CustomerNo=10 StartFrom=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 report.jasper -t mysql -u myuser -f pdf -H myhost -n mydb \ -o report -p secret -P background=/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 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
or quote the whole parameter:
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
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 or there is a special handler implemented for it.
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 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 myreport.jasper -f view -P MyDate=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 myreport.jasper -f view -P MyDate=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 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 myreport.jasper -f view -r myresources/
or
$ jasperstarter pr 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:
(...) myreports/report1 -f pdf odt
or
(...) myreports/report1.jasper -f pdf odt
or
(...) myreports/report1.jrxml -f pdf odt
results in:
myreports/report1.odt myreports/report1.pdf
If output is an existing directory, basename of input is used as filename in that directory:
(...) myreports/report1.jasper -f pdf odt -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:
(...) myreports/report1.jasper -f pdf odt -o month01/journal.xyz
results in:
month01/journal.xyz.odt month01/journal.xyz.pdf