2.7. Deployment

2.7.1. Introduction

EspressReport consists of several components: Report Designer, Report Viewer, Page Viewer, Chart Viewer, Scheduler, EspressManager, and Report API. Report Designer is used to create reports in a GUI environment. Report Viewer is an applet used to view already created reports (saved in .rpt/.xml/.pak format). Page Viewer is an applet that is used to view a report page by page (saved in .page format). Chart Viewer is an applet that is used to view a chart (saved in .cht/.tpl format). Report API is used to create reports programmatically. Scheduler is used to schedule exports for reports. Finally, EspressManager serves as a user administrator and handles data and data buffering.

[Note]Note

qblicense.jar must be included in the CLASSPATH or in the HTML page as an archive (along with any other additional jars) in order to run any code.

While the Report Designer and Scheduler must be used in conjunction with EspressManager, an option is provided for Report Viewer, Page Viewer, Chart Viewer, and Report API to work without connecting to EspressManager.

You must specify the information about how to connect to EspressManager. If EspressManager is running as an application, you can use API methods to specify the IP address/machine name where EspressManager is located and the port number EspressManager is listening on.

You use the following two API methods to set the connection information:

static void setServerAddress(java.lang.String address);
static void setServerPortNumber(int port);

For example, the following lines of code:

QbReport.setServerAddress("someMachine");
QbReport.setServerPortNumber(somePortNumber);

will connect to EspressManager running on someMachine and listening on somePortNumber.

[Note]Note

If EspressManager connection information is not specified, the code will attempt to connect to EspressManager on the local machine and listening to the default port number (22071).

If EspressManager is running as a servlet, you can use the following methods:

public static void useServlet(boolean b);
public static void setServletRunner(String comm_URL);
public static void setServletContext(String context);

For example, the following lines of code:

QbReport.useServlet(true);
QbReport.setServletRunner("http://someMachine:somePortNumber");
QbReport.setServletContext("EspressReport/servlet");

will connect to EspressManager running at http://someMachine:somePortNumber/EspressReport/servlet.

Please note that these methods exist in the QbChart, QbReportDesigner, QbChartDesigner, QbScheduler, and ScheduleModifier classes as well.

For Page Viewer and Report Viewer (in an applet), you can set the connection information to the EspressManager by passing in the following parameters:

server_address (server address), server_port_number (port number)

The above parameters are set if EspressManager is running as an application. If EspressManager is running as a servlet, the following parameters are used:

comm_protocol (servlet), comm_URL (machine name/IP address and port number), servlet_context (servlet context)

Described, in sections below, are the various deployment scenarios that you may encounter and the consequences of each scenario.

2.7.2. Deploying with EspressManager

This section deals with deploying report components that work in conjunction with EspressManager.

To learn more about the interaction, please refer to the Interaction with EspressManager section under the EspressReport Report API Overview chapter.

[Note]Note

Any references to a data source or a report file, using the relative URL reference (i.e. help\examples\data\sample.dat) are relative to the directory from where EspressManager is running in.

2.7.2.1. Report Designer

As mentioned before, Report Designer must be used in conjunction with EspressManager. Report Designer can be called using the API. Note that in this scenario, you will have to add ReportDesigner.jar in your CLASSPATH and place a copy of the reportimages (EspressReport/reportimages), images (EspressReport/images), and the backgroundImages (EspressReport/backgroundImages) directories under the working directory of the .class file.

Instead of copying the directories relative to the working directory when invoking the Report Designer from API, an option to set the location images/, reportimages/ and backgroundImages/ directory is also available. Simply use a QbReportDesigner constructor with the parameter imagesPath. For more detail about the QbReportDesigner constructor or the imagesPath parameter, please refer to the EspressReport Java API Documentation.

To connect to EspressManager running as an application, you use the following two API methods in QbReportDesigner to set the connection information:

static void setServerAddress(java.lang.String address);
static void setServerPortNumber(int port);

To connect to the EspressManager running as a servlet, you use the following three API methods in QbReportDesigner to set the connection information:

static void useServlet(boolean b);
static void setServletRunner(String comm_URL);
static void setServletContext(String context);

Please note that specifying the connection information to EspressManager must be made before calling any QbReportDesigner constructors.

2.7.2.2. Report Viewer

Report Viewer can be used in an applet or application environment to show a report saved in a .rpt/.xml/.pak file (either generated by Report Designer or Report API).

To deploy Report Viewer in an applet environment, the ReportViewerWithChart.jar must be included in the HTML file as the archive file.

To use Report Viewer, construct an HTML page with the proper applet code (for more details, please refer to the Report Viewer chapter). Note that any relative references to the report location and/or data are relative to the directory from where EspressManager has been started.

To connect to EspressManager running as an application, you must pass the following parameters to the Report Viewer applet:

server_address (server address), server_port_number (port number)

To connect to EspressManager running as a servlet, you pass the following parameters to the Report Viewer applet:

comm_protocol (servlet), comm_URL (machine name/IP address and port number), servlet_context (servlet context)

2.7.2.3. Page Viewer

Page Viewer can be used in an applet or application environment to show a particular page of a report at a time. These PAGE files are of .page file extension and are generated by Report Designer or the Report API.

To deploy Page Viewer in an applet environment, the PageViewer.jar must be included in the HTML file as the archive.

To use Page Viewer, construct an HTML page with the proper applet code (for more details, please refer to the Page Viewer chapter). Note that any relative references to the report location and/or data are relative to the directory from where EspressManager has been started.

To connect to EspressManager running as an application, you pass the following parameters to the Report Viewer applet:

server_address (server address), server_port_number (port number)

To connect to EspressManager running as a servlet, you must pass the following parameters to the Report Viewer applet:

comm_protocol (servlet), comm_URL (machine name/IP address and port number), servlet_context (servlet context)

2.7.2.4. Chart Viewer

Deploying Chart Viewer is similar to deploying Report Viewer. Chart Viewer can be used in an applet or application environment to show a chart saved in a .cht or .tpl file (either generated by Designer or API).

To deploy Chart Viewer in an applet environment, EspressViewer.jar must be included in the HTML file as the archive.

To use Chart Viewer, construct an HTML page with the proper applet code (for more details, please refer to start the Chart Viewer chapter). Note that any relative references to the chart location and/or data are relative to the directory from where EspressManager has been started.

To connect to EspressManager running as an application, you must pass the following parameters to the Report Viewer applet:

server_address (server address), server_port_number (port number)

To connect to EspressManager running as a servlet, you must pass the following parameters to the Report Viewer applet:

comm_protocol (servlet), comm_URL (machine name/IP address and port number), servlet_context (servlet context)

2.7.2.5. Report API

Report API can be used in either an applet environment or as an application. Report API can also be used in a servlet or jsp environment to generate server-side reports.

To deploy Report API, ReportAPIWithChart.jar, and ExportLib.jar must be in the CLASSPATH (for application and servlet/jsp environment) or included in the HTML file (for an applet).

To connect to EspressManager running as an application, you would use the following methods in QbReport to set the connection information:

static void setServerAddress(java.lang.String address);
static void setServerPortNumber(int port);

To connect to EspressManager running as a servlet, you would use the following methods in QbReport to set the connection information:

static void useServlet(boolean b);
static void setServletRunner(String comm_URL);
static void setServletContext(String context);

Please note that specifying the connection information to EspressManager must be made before calling any QbReport constructors.

2.7.2.6. Scheduler

A scheduler has also been included with EspressReport. This Scheduler can be used to export reports from their source files at specific intervals. For more information on the Scheduler, please look in the Scheduler chapter.

Like Report Designer, Scheduler must also be used in conjunction with EspressManager. Scheduler can be called using the API. Note that in this scenario, you will have to add Scheduler.jar in your CLASSPATH.

To connect to EspressManager running as an application, you use the following two API methods in QbScheduler/ScheduleModifier to set the connection information:

static void setServerAddress(java.lang.String address);
static void setServerPortNumber(int port);

To connect to the EspressManager running as a servlet, you use the following three API methods in QbScheduler/ScheduleModifier to set the connection information:

static void useServlet(boolean b);
static void setServletRunner(String comm_URL);
static void setServletContext(String context);

Please note that specifying the connection information to EspressManager must be made before calling any QbScheduler/ScheduleModifier constructors.

2.7.3. Deploying without EspressManager

This section deals with deploying components that work independent of EspressReport. To learn more about the interaction, please refer to the Interaction with EspressManager section under the EspressReport API Overview chapter.

Generating reports/charts independently of EspressManager results in a slightly better performance as the interaction of EspressManager and the report/chart component is removed.

An important consideration is that any references to a data source or a report source, that is relative (i.e. for example help\examples\data\sample.dat), are relative to the working directory from where the HTML file (in the case of an applet) or the class file (in an application) is being executed. In a servlet/jsp environment, the working directory typically differs from the directory where the class resides. To find out the working directory, have the following line of code in your servlet/jsp:

System.out.println("The working directory is " + System.getProperty("user.dir") + ". ");

By having the above line of code, and executing the servlet/jsp, the working directory is ascertained and the data files and report templates can be moved to locations relative to the working directory, as dictated by the code.

2.7.3.1. Report Viewer

To deploy Report Viewer, ReportViewerWithChart.jar must be included in the HTML file as the archive. Depending on what functionality you are using, you have to include additional jars as necessary.

Report Viewer can be used independent of EspressManager with the addition of one more parameter in the applet code:

<param name="EspressManagerUsed" value="false">

Note that any relative references to the report location and/or data are relative to the directory where the HTML file is located. For example, if the data source specified in the .rpt file is help\examples\data\sample.dat and if the HTML file is located in D:\EspressReport\TestApplet, then for the report to be displayed successfully, help\examples\data\sample.dat must exist within D:\EspressReport\TestApplet (i.e., D:\EspressReport\TestApplet\help\examples\data\sample.dat must exist).

2.7.3.2. Page Viewer

To deploy Page Viewer, PageViewer.jar must be included in the HTML file as the archive. Depending on what functionality you are using, you have to include additional jars as necessary.

Page Viewer can be used independent of EspressManager with the addition of one more parameter in the applet code:

<param name="EspressManagerUsed" value="false">

Note that any relative references to the report location and/or data are relative to the directory where the HTML file is located. For example, if the data source specified in the .rpt file is help\examples\data\sample.dat and if the HTML file is located in D:\EspressReport\TestApplet, then for the report to be displayed successfully, help\examples\data\sample.dat must exist within D:\EspressReport\TestApplet (i.e., D:\EspressReport\TestApplet\help\examples\data\sample.dat must exist).

Also note that when using Page Viewer without connectng to EspressManager, you cannot pass in a template directly. You must pass in the page file instead.

2.7.3.3. Chart Viewer

To deploy Chart Viewer, EspressViewer.jar must be included in the HTML file as the archive. Depending on what functionality you are using, you have to include additional jars as necessary.

Chart Viewer can be used independent of EspressManager with the addition of one more parameter in the applet code:

<param name="EspressManagerUsed" value="false">

Note that any relative references to the report location and/or data are relative to the directory where the HTML file is located. For example, if the data source specified in the .rpt file is help\examples\data\sample.dat and if the HTML file is located in D:\EspressReport\TestApplet, then for the report to be displayed successfully, help\examples\data\sample.dat must exist within D:\EspressReport\TestApplet (i.e., D:\EspressReport\TestApplet\help\examples\data\sample.dat must exist).

2.7.3.4. Report API

To deploy Report API, ReportAPIWithChart.jar and ExportLib.jar must be in the CLASSPATH (for application and servlet/jsp environment) or included in the HTML file (for an applet).

Report API can also be used without connecting to EspressManager by adding the line of code below:

QbReport.setEspressManagerUsed(false);

This method must be called prior to any QbReport instantiation.

As with Report Viewer, any relative references to the report location and/or data are relative to the working directory from where class file is being executed. For example, if the data source specified is help\examples\data\sample.dat and if the class file is located in D:\EspressReport\TestApplication, then for the report to be displayed successfully, help\examples\data\sample.dat must exist within D:\EspressReport\TestApplication (i.e., D:\EspressReport\TestApplicationhelp\examples\data\sample.dat must exist).

Note that any charts created in Report Designer will contain a relative path to the template. Therefore, the directory structure must be mirrored under the working directory (i.e., create a chart sub-directory with the template under the working directory), or open the template and change the path with an absolute path using the following code:

// Get the Chart from the footer
ReportChartObject obj = (ReportChartObject)report.getTable().getFooter().getData(0);
String originalLocation = obj.getText();
String newLocation = new String("http://128.0.0.1/EspressEnterprise/EspressReport/test/chart/chart/EspressReport1.1_0.tpl");
obj.setText(newLocation);

In a servlet/jsp environment, the location of the directory with the class file and the working directory might differ. In that case, any relative references are with respect to the working directory. For example, if the servlet class file was in D:\<some servlet engine>\webapp\examples\quadbase\someservlet.class and the data source was help\examples\data\sample.dat and the working directory was D:\<some servlet engine>\webapp, then help\examples\data\sample.dat must exist under D:\<some servlet engine>\webapp (i.e., D:\<some servlet engine>\webapp\help\examples\data\sample.dat must exist) for the report to be generated successfully.

Note that in the API, methods are also available that allow you to specify the location of the chart, drilldown, image, and subreport directories where certain files may be located. For instance, given the existence of a template, EspressReport1.1_0.tpl, in the report, you can specify the location this template by using the following code:

report.setChartPath("d:/EspressReport/Chart/");        // where report is an object of type QbReport

The above code sets the location of the template file thus avoiding the need to have a chart sub-directory under the working directory of your class file.

The following methods work similarly:

QbReport.setDrillDownPath(String directory);
QbReport.setImagePath(String directory);
QbReport.setSubReportPath(String directory);

Alternative to deploying your report in RPT format, you can also pack your report in PAK format and deploy it as a PAK file. This alternative simplifies the deployment procedures by including all the chart, sub-report, and drill-down files that are associated with your RPT file. To do this in the API, simply use the following method to pack your report file:

pack(java.lang.String filename, java.lang.String subReportPath, java.lang.String drillDownPath, java.lang.String chartPath);

During deployment onto your destination machine, simply open the report using the QbReport constructor with your PAK file name in the template parameter.

2.7.4. Deploying in a Non-Windows Environment

EspressReport is a Pure Java tool for generating reports. As such, it does not contain graphical libraries for generating colors and fonts and other AWT information. For that, Java relies on the system's (on which the reports are being generated) libraries for providing that information. Thus an environment capable of providing AWT information and a graphics card (for exporting to static formats) are required.

In a Windows environment, nothing extra needs to be done to set up such an environment as it already exists. A GUI interface is already running and a graphics card already exists.

For non-Windows environments (such as Unix and Linux), such is usually not the case. You need to have X or some form of X running on such systems and point the display to the machine running X (such as running the command export DISPLAY=192.168.0.16:0.0 in a shell). For best performance, Quadbase recommends running X on the machine (or setting the DISPLAY to point to another machine running X). However, if that is not an acceptable solution, there are alternative solutions available.

2.7.4.1. Xvfb (X Virtual Frame Buffer)

Xvfb is an X server that can run on machines with no display hardware and no physical input devices. It emulates a dumb terminal framebuffer using virtual memory.

The primary use of this server is intended to be server testing. Xvfb is also limited in the number of colors and fonts it can handle.

Xvfb can be downloaded (there are different version available depending on the system) and then run. After Xvfb is running, the DISPLAY variable needs to be set, and then passed to the application (or the servlet engine).

2.7.4.2. JVM 1.5+ in Headless Mode

You can use a 1.5+ JVM run-time parameter to run applications using EspressReport. The run-time parameter is java.awt.headless and setting it to true results in Java not making an X connection for any graphics information. For example, if you have an application called chartExport that generates charts as jpg's, ordinarily running it would involve making a connection to X. However, using the following command:

java -Djava.awt.headless=true exportChart

the same application is now run without a connection to X.

2.7.5. Platform Specific Issues

2.7.5.1. AS/400

2.7.5.1.1. Running under NAWT

To run any application using EspressReport in an AS/400 environment using NAWT, you must do the following:

  • Set the DISPLAY environment variable to the system name and display number. The display number is the display number of the VNC server.

  • Set the XAUTHORITY variable to /home/VNCProfile/.Xauthority, where VNCProfile is the profile that started the VNC server. Please note that XAUTHORITY need not be set if both the VNC server and the Java virtual machine is running under the same user profile.

  • Set the Java system property before running java

    os400.awt.native=true
2.7.5.1.2. Running under Headless Mode

To run any application using EspressReport in an AS/400 environment using headless mode, you must do the following:

  • Set the Java system property before running java

    java.awt.headless=true
  • Make sure that your code include the following before calling any QbChart constructor:

    QbChart.setForExportOnly(true);

2.7.5.2. Linux/Unix

2.7.5.2.1. Running under X

To run any application using EspressReport in a Linux/Unix environment using X, you must do the following:

  • Set the DISPLAY environment variable to a X client system name and display number.

2.7.5.2.2. Running under Headless Mode

To run any application using EspressReport in a Linux/Unix environment using headless mode, you must do the following:

  • Set the Java system property before running java

    java.awt.headless=true
  • Make sure that your code include the following before calling any QbChart constructor:

    QbChart.setForExportOnly(true);