1.) Overview/Introduction

Welcome to EspressReport.  Written in 100% pure Java, EspressReport is a set of tools that allows you to easily create professional, information-rich reports from a variety of data sources, and include them in your applications, Web based or otherwise. Among other components, EspressReport comes with a report designer and a robust object oriented API.  The report designer provides a powerful, yet easy to use graphical user interface, where users can quickly manipulate and format content, turning raw data into polished reports in a matter of minutes.  The finished report design can be saved in a template for subsequent distribution with up-to-the-minute data.  To publish the report on the Web, you will write JSP/servlet code using the API to reference the template and generate the report in a desired format.  Export formats supported include PDF, HTML, DHTML, text, and Excel spreadsheets.  Reports can also be viewed in a browser with Report Viewer or EspressReport’s API running as applet, and printed in a WYSIWYG hard copy.

Included in the report designer is a query builder and data source manager that allow you to quickly extract data from JDBC, ODBC, XML, and ASCII sources.  The sophisticated Data View features allow administrators to create local data catalogs for end users, and present data from databases in simplified terms.  Using this feature, end users who have no knowledge of database can easily perform ad-hoc reporting.

To facilitate easy report design/creation, EspressReport supports five report types, namely, simple columnar, summary break, crosstab, master & details and mailing labels.  Advanced features allow users to include sub-reports, drill-down, parameters, insert hyperlinks, insert images, manipulate data with over eighty-five built-in formulas, and incorporate sophisticated charts and graphs into reports.

1.1.) Version 5.5 New Features

Version 5.5 contains many new features and enhancements.

  1. Cascading parameters enhancement - Cascading parameters are now supported in subreports and drilldowns, cascading parameters can also be used in conjunction with linked sub-reports.

  2. Ability to delete scripts even if it is applied on certain cells, see Designer Chapter, Section 9.

  3. Open report and canceling no longer closes the previous report.

  4. Chart colors now map to category or data series names, see Charting Chapter, Section 5.

  5. Dynamic step interval - User can now specify label step units for dates as dynamic, which will automatically calculate the interval based off of the data range. See Charting Chapter, section 5.7.2.

  6. Chart zooming enhancement - In the chart viewer, changing the range will dynamically change the scale. See Charting Chapter, section 5.8.2.2.

  7. New option to hide 0% elements in a pie chart. See Charting Chapter, Section 5.9.4.

  8. Background images in charts can now be saved with relative URL. See Charting Chapter, Section 5.5.1.1.

1.2.) EspressReport Documentation

There are four sections to the EspressReport Documentation.

2.) Architecture & Installation

There are seven main components to EspressReport, namely, Report Designer, Chart Designer, Report API, Report Viewer, Page Viewer, EspressManager, and Scheduler.

2.1.) EspressReport Architecture

EspressReport has a number of different configurations in which it can run both at design-time, and at run-time.  At design-time the Report Designer GUI interface, which includes data access tools, and charting tools can be loaded as an application on a client machine, or as an applet in a client server architecture.  The following diagram illustrates EspressReport running with the Report Designer at design-time.


EspressReport Designer Architecture

When Report Designer is running, the EspressManager component runs on the server-side.  It can run either as an application process, or as a servlet deployed within an application server/servlet runner.  The EspressManager performs the data access and the file I/O which is prevented by the client applet due to security restrictions.  The EspressManager also provides connection and data buffering for database connections, as well as concurrency control for a multi-user development environment.  The EspressManager must be run in conjunction with the Report Designer.

At run-time, the EspressManager does not need to be running.  EspressReport is designed to run embedded within other application environments, and can have a minimal deployment of the API classes, and report template files.  The following diagram illustrates EspressReport running in a servlet/JSP environment.


EspressReport in a Servlet Environment

When running in an application server, the Report API can be used to generate reports within servlets and JSPs and stream the generated report to the client browser. Clients can also view reports, by loading the Report Viewer applet or the Page Viewer applet.

Report generation can be handled on demand, triggered by application processes, or scheduled. A scheduler interface is also provided with EspressReport. In order to run the scheduler the EspressManager must also be running.

In addition to running in a client-server environment, EspressReport can be run in a thick-client application.  The Report API can be used in conjunction with the Viewer and/or Page Viewer to show/generate reports in an application interface.  In this configuration, EspressManager does not need to be running, as the whole process can be contained on the client.  Note that this is not the case for applets.

2.2.) Installation

There are four versions of EspressReport installer available, one for Windows, one for Unix, one for Mac OS X, and a pure Java version.

Once the installation program has launched and you agree to the license agreement, the first option that is presented asks you whether you would like to install the evaluation or release version.


Install Version Dialog

If you elect to install a release version, then the next dialog will prompt you to enter your license key, and verify the host name of the machine on which you're installing EspressReport.


Enter License Key Dialog

After you have entered the information, the installer will attempt to register the license key with Quadbase.  If registration fails, you will be unable to continue installing the release version of EspressReport.  You will have the option to continue installing the evaluation version.  After the installation completes, you can register your key online at http://www.quadbase.com/register.jsp, or contact Quadbase Sales for additional help.

*Note - After the installation completes, the release version will only run for the hostname specified in this dialog, so double-check to make sure the host name is correct.  You can also use the IP address of the machine if you prefer.

Once the license key has been successfully registered, or if you select to install the evaluation version, the next dialog will prompt you to specify the install location.


Choose Location Dialog

The default location is \EspressReport\.  You can specify a new directory, or browse to one by clicking the 'Choose…' button.

The next option allows you to specify a Java Virtual Machine to use when running EspressReport.  (Since it is a Java program, you will need a JVM to run it.)


Choose JVM Dialog

You can choose to install a JVM that comes with EspressReport, or choose a JVM that you have already installed on your system. The installer searches for any JVMs and presents you with a list to choose from. If the JVM you want to use is not listed, you can click the 'Choose Another...' button to browse to it.

*Note - The JVM that is bundled with the installer only provides a Java Runtime Environment.  In order to develop and execute Java code using the Report API, you will need to have a Java Development Kit, and/or compiler/IDE.  Also, if you're using the pure Java, or Mac OS X version of the installer, this option will not appear.  Make sure that you're running the installer with the JVM you wish to run the program.

The next option in the installer is only for the Windows release version of the installer.  It is not available for the Unix or pure Java versions, and is not available for any evaluation versions of EspressReport.  This option allows you to run EspressManager as a Windows NT/2000 service.


NT/2000 Service Dialog

*Note - In order for EspressManager to run correctly as a Windows service, you will need to have DirectX v8.1 or higher installed on your Windows system.  EspressManager may not run correctly with older versions of DirectX.

If you specify to start EspressManager as a service, two new options will follow.  First, you will be prompted to specify some configuration information for EspressManager.


EspressManager Configuration Dialog

These options are the same as command line arguments that are available when you run EspressManager using the .bat or .sh file.  For more information about configuring EspressManager, see Section 2.3.

If you're running EspressManager as a Windows service, the next option in the installer will prompt you whether you would like to add the classes for a JDBC driver to the EspressManager Classpath.  This will allow you to connect to a database to retrieve report data.  (You can manually modify the .bat or .sh files to add classes.)  If you select to add a driver, the next option will allow you to specify the file you would like to add.

The last option in the installer is for the Windows, or Mac OS X installation. It allows you to specify where to create the program shortcuts in the Start Menu, on the Desktop, or both. By default shortcuts are added to a program group called EspressReport in the Start Menu.

For Mac OS X you can create aliases on the Desktop, in the dock, or in a folder of your choosing.

After you complete the last option you will be shown a summary of the options you've selected.  Next, the program will install.

2.2.1.) Configuration

After installation, the configuration should be set and EspressReport will run without any modification.  However, if you want to change the port number for connecting to EspressManager, change the webroot, or add/delete/modify users, you can do this by modifying the config.txt in the userdb directory. 

Below is a sample config.txt file:

Under the [port] section you can set the port number for EspressManager to use.  By default this number is set to 22071.  You can also give an explicit IP address here for EspressManager to use instead of making EspressReport query the machine for the IP address.  An explicit IP address can be given by adding the address after the port number.  For example, changing

will result in EspressManager always using that IP address when it starts.  You can also specify multiple domains for EspressManager to use to establish a connection in the [port] section of the config.txt file.  Domains are added after the IP address in the [port] section.

The search sequence is the IP address, then domain_n through domain1.

Under the [users] section, each line consists of a user name and password.  A default username = "guest" with password = "" is set up for you.  You can remove this line if you like.  Each name and password are separated by one or more spaces (so all user names and passwords should not have spaces within them).

Each development license allows only one concurrent user to be logged on.  If you purchased more then one development license, then you can set up the development kits on separate machines, or set up concurrent users on a single machine.

*Note - There is no limit to the number of users who have login privileges to EspressManager.  This license restriction applies only to the number of simultaneous users.

The [smtp host] section allows you to specify the smtp server name to be used when sending email notification or reports with the scheduler.  For more information about using the scheduler, please see Chapter 13.

When EspressManager is started it will generate a configuration file called EspressManager.cfg in the directory in which it is started.  This file contains the IP address and port number on which EspressManager is listening as defined in the config.txt file.  When Report Designer is started, it will look for this file for connection information to EspressManager.  If it can't find this file it will use the default IP of 127.0.0.1 (localhost) and port 22071.

Other EspressReport components, and applications/servlets/JSPs using the Report API will also, by default, look for the EspressManager.cfg file to make a connection to EspressManager.  However, with the Report Viewer, Page Viewer, and Report API, you can explicitly set the IP and port that the component should use to connect to EspressManager.  For more information about deploying EspressReport components, please see Chapter 7 of the Programming Guide.

2.2.1.1) Increasing maximum memory heap size for applets

All applets have a maximum memory heap size of 16 megs, by default.  In Windows, this can be increased by going to Control Panel and selecting Java (or Java Plugin).  Click on the "Java" tab and then "View" under "Java Applet Runtime Settings".  Enter "-Xmx128M" (without the double quotes) under "Java Runtime Parameters" and click "OK".

Note that the above is applicable if a Sun 1.5 or 1.6 JVM has been installed.  If a Sun 1.4 JVM has been installed, the "Java Runtime Parameters" option can be found under the "Advanced" tab.

2.3.) Starting EspressManager

Before Report Designer can be started, EspressManager must be running.  In most installations, EspressManager should be started on the web server machine.  It is possible to use EspressReport on a stand-alone machine, running both EspressManager, and Report Designer locally. In this case, the IP number assigned will be 127.0.0.1.  This will create a log file, espressreport/EspressManager.log, which may be useful in monitoring usage as well as diagnosing problems.  It is not necessary to install or start EspressManager on each Report Designer user machine.

To start EspressManager, run the EspressManager.bat or .sh file in the EspressReport root directory.  (You can also execute the shortcut/alias for Windows or Mac).  EspressManager will then start automatically with the default attributes.

You can also configure EspressManager with your own settings using several arguments that have been provided.  The argument assumes the format of a dash '-' followed by a command set.  No space is needed in each argument but at least one space is required to separate different arguments.

You can enter these arguments in the command line when starting EspressManager.  You can also edit the espressmanager.bat/.sh file to add arguments, or you can enter the arguments in the ServerCommands.txt file in the /userdb/ directory of the EspressReport installation.  Arguments in the text file are also picked up when EspressManager is started as a servlet process.  For more on this please see section 2.3.2.


EspressManager Monitor

If you're running on Mac OS X and you elected to create aliases when installing, you will need to modify the espressmanager.app package to to change the EspressManager settings.  To do this righ-click (CTRL+Click) on espressmanager.app and select 'Show Package Contents' from the pop-up menu.  Then navigate to the Contents folder where you will see a file called 'Info.plist'.  Open this add the arguments to the "lax.command.line.args" argument under Java properties.

2.3.1.) EspressManager Configuration Interface

Many of the EspressManager configuartion features highlighted in the previous section can also be set using a stand-along EspressManager configuration interface provided with EspressReport.  To launch the interface, make sure the EspressManager is not running, and execute the ManagerConfig.bat/.sh file.  This will open the configuration window.


EspressManager Configuration Window

The following configuration options can be set in this interface:

For a description of all the options listed above, please see the previous section.  In addition to the configuration options, users can also append EspressManager's CLASSPATH using this interface.  Database drivers and other external classes can be added to EspressManager, by clicking the 'Insert' button and browsing to the desired file.

When you click Apply, changes to the configuration options will be saved to the ServerCommands.txt file, and the CLASSPATH changes will be saved to the EspressManager.bat/.sh file.

2.3.2.) Starting EspressManager as a Servlet

In addition to running as an application process, EspressManager can be run as a servlet within an application server/servlet runner.  In this environment, EspressManager uses http to communicate with the client instead of sockets.  The advantage to this configuration is that EspressManager can share the same port as the application server which makes it easier to deploy from behind firewalls.  In addition, users can perform remote administration when running EspressManager this way.

To deploy EspressManager as a servlet, complete the following steps:

  1. Copy the EspressManager.jsp, MenuError.jsp and /WebComponent/ directory under the application server root (or virtual directory) such that they are accessible via http

  2. Copy the contents of the EspressReport/classes directory and make the classes available via a servlet context.

  3. Copy the QuadbaseDirectory.cfg file from the EspressReport installation directory to the working directory of the application server.  To find out the working directory, run whatIsMyWorkingDirectory from the servlet context where you copied the EspressManager servlet classes.  The servlet will print the working directory path in your browser when it is called.

  4. Add EspressManager.jar from the /lib/ directory of the EspressReport installation to the application server's CLASSPATH.  You may also want to add parser.jar and jaxp.jar from the /lib/ directory depending on the application server in use (Tomcat, for example already has the XML parsers).  If you're using the scheduler to email reports you will also need to add mail.jar and activiation.jar from the /lib/ directory to the CLASSPATH.  Finally, you may also need to add the classes for your JDBC driver in order to make a connection from EspressManager to a database.

  5. Re-start the application server.

Once all these steps have been completed, you should be able to load the EspressManager page, by pointing your Web browser to the EspressManager.jsp page that should be available in your application server as explained in step 1.


EspressManager JSP Monitor

With this page loaded, click the 'Start' button to start EspressManager.  Once it is started, you can set/modify the buffer settings, and shut it down again from this window.  With EspressManager running, you can close this window.  It will continue to run, untill you call the JSP again and shut it down.

When running EspressManager as a servlet, all of the components that connect to EspressManager need to be modified to take this into account.  This includes Report Designer, Scheduler, Report Viewer, Page Viewer, and any application/servlet/JSP using the Report API.  For more information about EspressReport deployment, please see Chapter 7 of the Programming Guide.

2.3.2.1) Deploying EspressManager as a servlet in Tomcat 4.x

The following section explains how to setup and run EspressManager as a servlet in Tomcat 4.x.  The steps are the same as those mentioned in the previous section.  This example assumes you are running Tomcat locally (IP 127.0.0.1) over port 8080.  If your configuration is different, simply replace the IP and port in these instructions with those that you are using.

  1. Create a directory named "EspressReport" under your Tomcat root (<Tomcat installation directory>/webapps/ROOT).  Copy the EspressManager.jsp, MenuError.jsp files, and the /Web_Component/ directory from your EspressReport installation (<EspressReport Installation Directory>) to the new /EspressReport/ directory under the Tomcat root.

  2. Copy the contents of the <EspressReport Installation Directory>/classes directory to the <Tomcat Installation Directory>/webapps/ROOT/WEB-INF/classes directory.  You will need to make sure that the invoker isn't commented out from the <Tomcat Installation Directory>/conf/web.xml file.  (This is commented out by default in Tomcat, and doesn't allow the "/servlet/" context to be available).  For more information about the Tomcat invoker servlet, please see section 4.1 of the Quick Start Guide.

  3. Copy the QuadbaseDirectory.cfg file from the EspressReport directory to the <Tomcat Installation Directory>/bin directory.  (Generally this is the working directory for Tomcat.  However, if you start Tomcat in another location the working directory may be different.  To check your working directory open your Web browser, and with Tomcat running type "http://127.0.0.1:8080/servlet/whatIsMyWorkingDirectory".  This servlet will display the path to the working directory.) If your working directory is something other then /bin/, place the QuadbaseDirectory.cfg file there.

  4. Add the EspressManager.jar file (under <EspressReport Installation Directory>/lib) to Tomcat's CLASSPATH.  Generally this is done by editing the setclasspath.bat or .sh file in the <Tomcat Install Directory>/bin directory.

  5. Restart your Tomcat server.

Now EspressManager should be deployed correctly.  To start EspressManager, open your Web browser and go to the following address: "http://127.0.0.1:8080/EspressReport/EspressManager.jsp".  The Monitor will load, and you can start EspressManager by clicking the 'Start' button.

2.4.) Starting Report Designer


Report Designer Login Window

2.4.1.) Connecting Report Designer to EspressManager Running as a Servlet

If EspressManager is running as a servlet as described in section 2.3.1, you will need to make some modifications before Report Designer can be started successfully.