Usage

Installation

Windows users

Unzip the distribution archive to a directory of your choice for example:

C:\App\jasperstarter

Add the directory

C:\App\jasperstarter\bin

to your user or system path variable

or simply use the setup.exe

Linux users

Extract the distribution archive to a directory of your choice for example:

/opt/jasperstarter

Add the directory

/opt/jasperstarter/bin

to your user or system path.

Invoking JasperStarter

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

Concepts

JasperReport files

JasperReports know three types of files:

  • The report definition file myreport.jrxml

    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.

  • The compiled report file myreport.jasper

    This file is the result of compiling an .jrxml file.

  • The filled report file myreport.jrprint

    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.

Stages of processing

There are three stages of processing a JasperReport:

  • compiling results in a .jasper file
  • filling can optionally be stored in a .jrprint file
  • viewing, printing or exporting to one or more of the supported formats

JasperStarter can carry out all of them in one commanding call.

JasperStarter commands and options

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 (cp)

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 (pr)

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>] [-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,   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"

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 (printers,lpr)

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 (params,lpa)

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:

  • P/N - Prompt or no promt flag
  • Parameter name
  • Parameter type (class name)
  • Optional description

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

Command files

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!

Processing reports

To process a report you must provide the process command pr which needs the following options:

  • <input> input file (report definition, compiled report or filled report).
  • -f a space separated list of output formats.
    • view and print are mutually exclusive thus print is ignored if view is given.
  • -t a database type if your report needs a database connection. Defaults to none.
    • if database type is not none you must specify the needed

      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:

  • -f -a -P -r

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 non database report

The minimum options needed, to process a report with an empty datasource:

$ jasperstarter pr myreport.jasper -f view

The minimum database report

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

View, print or export previously filled reports

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

Reports with a CSV datasource

The CSV file charset defaults to UTF-8. Other common used charsets are cp1252 (Windows), ISO-8859-1 or ISO-8859-15 (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:

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

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

Reports with runtime parameters

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:

  • date, image, locale

Multiple parameters can be separated by spaces. A parameter has the following form:

  • <name>=<value>

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
The image parameter

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:

  • Create a parameter in your report and change it's properties:
    • Name = background
    • Parameter Class = java.awt.Image
  • Place an image in your report and change it's properties:
    • Image Expression = $P{background}
    • Expression Class = java.awt.Image
  • compile your report

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
Quoting parameters that contain spaces

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
Prompt for parameters

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:

  • a - all parameters (including system parameters)
  • ae - all empty parameters (parameters for which no value is provided on command line)
  • p - all user defined parameters marked for prompting (this is the default if -a has no argument)
  • pe - all empty user defined parameters marked for prompting
  • u - all user defined parameters
  • ue - all empty user defined parameters

In the following examples we assume a non database report which has two parameters:

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

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 with resources

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

File Handling

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