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_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 (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] -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 (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> ...] -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 (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] -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:

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

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

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 -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!

Processing reports

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

  • -i 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".

The minimum non database report

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

$ jasperstarter pr -i myreport.jasper -f view -t none

The minimum database report

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

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

Reports with runtime parameters

Report parameters can consist of several types. Most types are self-explanatory. JasperStarter supports the following types:

  • string, int, double, date, image, locale

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

  • <name>=<type>:<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 -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
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 -t mysql -u myuser -f pdf -H myhost -n mydb -i report.jasper \
-o report -p secret -P background=image:/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 -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
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. 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:

  • 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 -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 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 -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

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:

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