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 a JNLP(More about Applets in JNLP: Section 1.2.7 - Run Applets in WebStart with JNLP file in a client server architecture. The following diagram illustrates EspressReport running with the Report Designer at design-time:

EspressReport Designer Architecture

When the 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 data access and 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 running 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. 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 side. 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 the installation directory, the next option asks you whether you want to install the evaluation or licensed version.

Install Version Dialog

If you select to install a licensed version, 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 enter all informations, the installer will attempt to register your license key with Quadbase. If the registration fails, you will be unable to install the release version of EspressReport. However, you will still be able to install the evaluation version. After the installation is complete, you can register your key online at https://www.quadbase.com/register/, or contact Quadbase Sales for additional help.

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

The next window allows you to specify which Java Virtual Machine version should be used to run EspressReport. (Since it is a Java program, you will need JVM to run it.)

Choose JVM Dialog

The dialog prompts you to select which Java Virtual Machine you want to use. A list of compatible JVMs on the system will be displayed, allowing you to pick one. If the JVM you want to use is not listed, you can click the Select Another Location... 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 Java Runtime Environment. In order to develop and execute Java code using the EspressReport API, you will need to have Java Development Kit and/or compiler/IDE. Also, if you're using 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 Windows or Mac OS X version of the installer. It allows you to specify the location of program shortcuts. By default the shortcuts are added to a program group called EspressReport in the Start Menu.

For Mac OS X, you can create aliases on desktop, in dock, or in a folder of your choice.

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

The configuration for EspressReport is already set and it can be run without changing anything. 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]
{user-name encoded-password}
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 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 IP address, domain_n, then domain1.

Under the [user] section, each line consists of username and password. Default username is guest with no password. You can remove this line and add as many additional users as you like. Each username and password are separated by one or more spaces (usernames and passwords cannot contain spaces). Also, usernames and passwords are case sensitive.

Each development license allows only one concurrent user to be logged on. If you purchased more than 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 that 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 used for 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 starts for the first time, 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 cases, EspressManager should be started on the web server, but it is possible to use EspressReport on a stand-alone machine by running both EspressManager and ReportDesigner locally. The assigned IP number will be 127.0.0.1. This will create a log file <EspressReportInstallDir>/EspressManager.log, which can be used to monitor resource usage as well as diagnose problems. It is not necessary to install or start EspressManager on each ReportDesigner user machine.

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

You can there also Add/delete/modify users.

"Manage Users" button can be used to add and remove user name and encrypted password in the config.txt file.

You can also configure EspressManager with your own settings using several arguments that have been provided. The argument starts with dash - followed by a command. 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 and 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 information about this, please see Section 1.2.4.2 - Starting EspressManager as a Servlet.

If you're running on Mac OS X and you selected 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, then execute ManagerConfig.bat/.sh. A configuration window will open.

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 the Apply button, all changes will be saved to espressmanager.bat/.sh.

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. As an example, Tomcat is located at C:\Tomcat and EspressReport installed to C:\ER70

1.2.4.2.1. Tomcat settings

To link Tomcat installation with our product installation, access the file "C:/Tomcat/conf/server.xml", and add your code defining one or more product installations between the "Valve" and "Host" sections.

<context path="/ER70" docBase="/home/user/Quadbase/TomcatER/ER"><Manager pathname=""/></context>

1.2.4.2.2. Startup settings

For Windows operating systems

Access the folder "C:/Tomcat/bin," copy the file "startup.bat" and paste it in your chosen installation of ER. Then, open the file and edit code to direct the Tomcat startup file to the Tomcat installation folder.

set "CATALINA_HOME=C:\Tomcat"

For Linux operating systems

Create a startup.sh file in <ER install directory> and make it executable.

Type the following two lines into the newly created <ER install directory>/startup.sh file

EXECUTABLE="<path to tomcat>/bin/catalina.sh"

exec "$EXECUTABLE" start "$@"

For example:

EXECUTABLE="/home/user/tomcat/bin/catalina.sh"

exec "$EXECUTABLE" start "$@"

	Note
	The rest of this guide is the same for Windows and Linux.

1.2.4.2.3. File launch settings

To make changes in the launching files, first, select the "EspressReport.jsp" find the end of the file and find the commented lines, and remove the comments.

<!-- Use these params if running EspressManager as servlet <param name="comm_protocol" value="servlet"/> <param name="comm_url" value="<%=codebase%>"/> <param name="servlet_context" value="servlet"/> -->

These are the parameters for connecting to EspressManager servlet, "servlet_context" may need edit, for example, in Tomcat/conf/servlet.xml, you configure your application as "/ER70", the value will be "ER70/servlet".

In the next step, you will need to edit "reportdesigner.bat" or "reportdesigner.sh" and append the following parameter at the end of the file: "-servlet:http://your-server-ip:your-port/ER70/servlet". Please note that this parameter must be placed at the end of the file, as placing it anywhere else will result in the designer being treated as a Java parameter and not run as intended.

When running EspressManager as a servlet, all components that connect to EspressManager need to be modified to take this into account. This includes Report Designer, Report Viewer, and any application/servlet/JSP using the Report API. For more information about EspressReport deployment, please see Section 2.7 - Deployment.

If you upgraded from an older version, you may notice some changes in the default behavior. Although the backward compatibility is kept as much as possible, sometimes a new behavior is preferred. The new behavior should be better for most 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 you are doing. If you are not sure, please contact support.

The patches can be found in <EspressReport_Installation_Directory>/lib/Patches directory. They are stored in JAR archives. To apply a patch, you only need 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 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 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 a list of all available patches in the current version.

Trying to run Java Applets in newer browsers and/or with newer Java versions can lead to problems with Applets being deprecated or not supported any more. Officially were Applets blocked to run in common browsers from about year 2016. However, it is still possible to run Applets in a similar use case as before (open a Java application from a remote server via your browser) thanks to Java WebStart technology that's supported by Java 8. Both Applets and Java Web Start are marked as deprecated technologies from Java 9.

Applets vs WebStart

In this case, EspressReport is Java 8 compiled application and is best to use it with Java 8. For using Applets with WebStart in newer versions, you must use some different implementation of WebStart. Popular choices are OpenWebStart or IcedTea-Web and it is already included in some newer Java distributions.

To run a Java Applet via a Java Web Start JNLP file, you have to specify the applet-desc parameter in the JNLP file configuration file.

   <applet-desc
      name="Chart Viewer"
      main-class="quadbase.chartviewer.Viewer"
      width="800"
      height="600">
	<param name="filename" value="help/examples/ChartAPI/data/test.tpl"/>
	<param name="preventSelfDestruct" value="true"/>
  </applet-desc>

The param tags specify parameters for the applet. The parameters are different for each applet. The specific parameters are mentioned in the documentation chapter for each applet.

JNLP files can be either run locally when the required libraries (containing the compiled source code) are loaded as a local file or remotely when the libraries are loaded via HTTP/HTTPS.

To run an Applet in a JNLP file remotely via HTTP/HTTPS, the EspressManager has to be run as a servlet in an application server. See the following chapter to learn how to do that: Section 1.2.4.2 - Starting EspressManager as a Servlet

When running JNLP files remotely via HTTP/HTTPS, the parameters comm_protocol, comm_url and servlet_context need to be added to the applet-desc element. You can either fill in the values manually (as the following code example shows) or you can have the values filled automatically in a JSP file.

<applet-desc
	 name="Espress Report Designer"
	 main-class="quadbase.reportdesigner.designer.ReportClient"
	 width="380"
	 height="160">
	<param name="comm_protocol" value="servlet"/>
	<param name="comm_url" value="http://127.0.0.1:8080"/>
	<param name="servlet_context" value="Espress70/servlet"/>
</applet-desc>

	Note
	If you want to pre-fil the values automatically in a JSP file, the actual values highly depend on your server configuration. The previous example is just illustrative.