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 environment. It 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 reports 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. EspressManager must be running in order to run the Scheduler.

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

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 asks you to specify the directory into which you would like to install EspressReport.

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

Choose Location Dialog

Once you choose an installation directory, the next option asks you whether you would like to install the evaluation or licensed version.

Install Version Dialog

If you elect to install a licensed version, the next dialog will prompt you to enter your license key and to 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/, 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.

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

The dialog prompts you to select which Java Virtual Machine you would like to use. A list of compatible JVMs on the system are displayed, allowing you to pick one. If the JVM you would like to use is not listed, you can click the Choose Another button to browse to it. When using the windows installer, you can also choose to install the JVM bundled with the installer, if a compatible JVM has not been found.

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 EspressReport 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 last option in the installer is for the Windows or Mac OS X version of the installer. 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.

The configuration for EspressReport is already set and EspressReport be run without changing the configuration. However, if you want to:

You will need to modify the configuration settings. These settings are stored in a text file called config.txt. It is in the following location: <EspressReportInstallDir>/userdb/config.txt. A sample configuration file is shown below:

[port]
22071

[webroot]
C:\Intepub\wwwroot

[users]
guest
Name1 Password1
Name2 Password2

[smtp host]
quadbase.com

[smtp secured]
true

[smtp ssl]
true

[smtp port]
587

[smtp username]
guest

[smtp password]
password
        

Under the [port] section you can set the port number for EspressManager to use. This number is set to 22071 by default. 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

[port]
22071
		

to

[port]
22071, 204.147.182.31
		

will result in EspressManager always using that IP address when it starts. You can 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.

[port]
port number, ip address, domain1, domain2, ..., domain_n
		

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

Under the [user] section, each line consists of a user name and password. A user name of guest with no password is set up by default. You can remove this line, and add as many additional users as you would like. Each user name and password are separated by one or more spaces (so user names and passwords cannot contain spaces). Also, user names and passwords are case sensitive.

Each development license allows only one concurrent user to be logged on. If you purchased more then one development license 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 Section 1.13 - Scheduling.

If your SMTP server requires authentication, fill in the following sections as well. If your SMTP server uses SSL/TLS, set [smtp ssl] to true.

[smtp secured], [smtp ssl], [smtp port], [smtp username], [smtp password]
		

Otherwise, you can leave these sections blank.

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 is not able to 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 in order to connect to EspressManager. For more information about deploying EspressReport components, please see Section 2.7 - Deployment.

Before ReportDesigner 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, by running both EspressManager and ReportDesigner locally. In this, the IP number assigned will be 127.0.0.1. This will create a log file, <EspressReportInstallDir>/EspressManager.log which may be useful in monitoring usage as well as in diagnosing problems. It is not necessary to install or start EspressManager on each ReportDesigner user machine.

To start EspressManager, run the EspressManager.bat or EspressManager.sh file in the EspressReport root directory (this file is generated automatically by the installation). For Windows installations you can use of the program shortcuts that were added to the start menu or desktop depending on the options that were specified during installation. EspressManager will then start automatically with default properties.

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/espressmanager.sh file to add arguments.

Arguments in the text file are also picked up when EspressManager is started as a servlet process. For more on this please see Section 1.2.4.2 - Starting EspressManager as a Servlet.

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 change the EspressManager settings. To do this, right-click (Ctrl+Click) on espressmanager.app and select Show Package Contents from the pop-up menu. Next, navigate to the Contents folder where you will see a file called Info.plist. Opening this file in a text editor adds the arguments to the lax.command.line.args under Java properties.

1.2.4.1. EspressManager Configuration Interface

Many of the EspressManager configuration 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:

• Log

• EspressManager Monitor on/off

• Run in Background on/off

• Record Limit

• HTML DPI

• Page Clean-up Time

• Single Table for Distinct Param Value

• Scheduler Callback Class

• Listener Manager Class

• Scheduler Thread Limit

• Schedule Buffer

• Record File Settings

• Default Global Format

• Default PDF Font Mapping

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 will be saved to the espressmanager.bat/.sh file.

1.2.4.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 EspressManager.jsp, MenuError.jsp and /WebComponent/ directory under the application server root (or virtual directory) in such way that they are accessible via http.

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

3. Copy the /html/ and /userdb/ directories from the EspressReport installation directory to the working directory of the application server(if not exist, create new empty folder). 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. Copy EspressManager.jar, qblicense.jar, encoder-1.2.2.jar and esapi-2.2.0.0.jar files(or corresponding versions) from <EspressReport Installation Directory>/lib to the application server's CLASSPATH. You may also want to add axercesImpl.jar and xml-apis.jar from /lib/ directory depending on the application server in use (for example, Tomcat already have XML parsers). In addition, you may also need to add the classes for your JDBC driver in order to make a connection from EspressManager to a database.

5. Restart 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 has 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 until 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 Section 2.7 - Deployment.

1.2.4.2.1. Deploying EspressManager as a Servlet in Tomcat

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

1. Create a directory named EspressReport under your Tomcat root folder (<Tomcat installation directory>/webapps/ROOT) and copy there EspressManager.jsp, MenuError.jsp files, and /Web_Component/ directory from your EspressReport installation (<EspressReport Installation Directory>).

2. Copy the <EspressReport Installation Directory>/classes directory to <Tomcat Installation Directory>/webapps/ROOT/WEB-INF/ directory.

3. Copy EspressManager.jar, qblicense.jar, encoder-1.2.2.jar and esapi-2.2.0.0.jar files(or corresponding versions) from <EspressReport Installation Directory>/lib to <Tomcat Installation Directory>/lib . Alternatively, you can link this files with Tomcat by creating setenv.bat under <Tomcat Installation Directory>/bin directory and write in Tomcat's CLASSPATH with the value of EspressManager.jar, qblicense.jar and servlet-api.jar.

   Sample of setenv.bat:

   set CLASSPATH=C:\EspressReport66\lib\EspressManager.jar;C:\EspressReport66\lib\qblicense.jar;C:\tomcat\lib\servlet-api.jar
   						

4. Copy the /html/ and /userdb/ directories from the EspressReport installation directory to <Tomcat Installation Directory>/bin directory(if not exist, create new empty folder).

5. Restart your Tomcat server.

Now EspressManager should be deployed correctly. To start the 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 the EspressManager by clicking the Start button.

If you upgraded from an older version, you may notice some changes in the default behavior. Although the backward compatibility is kept whenever it is possible, sometimes a new behavior is preferred. The new behavior should be better for majority of users, but if you already have some charts or reports from an older version, you may want to keep the old behavior, so your charts and reports look exactly the same as before. That is why we provide backward compatibility patches.

	Caution
	Patches are for advanced users only. Please apply them only if you need them and if you know what are doing. If you are not sure, contact support.

The patches can be found in the <EspressReport_Installation_Directory>/lib/Patches directory. They are stored in JAR archives. To apply a patch, it is enough to add the appropriate JAR file to the classpath of your application as described below.

If you want to apply a patch to all designers (for reports and charts) and viewers, you have to edit the espressmanager.bat and reportdesigner.bat files (if you use Windows) or espressmanager.sh and reportdesigner.sh files (if you use other OS) in your EspressReport installation directory and add relative path to the patch JAR file (e.g. ./lib/Patches/patch1.jar) to the classpath parameter. If you are running Report Designer from HTML page, you also have to edit the index.html file in your EspressReport installation directory and add relative path to the patch JAR file to the archive attribute of the applet tag.

If you are using API, you have to include the patch JAR file in the classpath of your application.

Below is list of all patches available in the current version.