Index

Executing Reports from JReport Beans Or APIs

Introduction

JReport is Java-centric object-oriented reporting tool written entirely in Java. We provide bean components, so that you can easily incorporate JReport in your own applications. JReport beans can be used inside IDE tools like JBuilder, Visual Café, Visual Age, and SilverStream. Additionally, please consult the next chapter, "Using JReport Beans in Forte™ for Java" for special instructions on using JReport beans in that IDE. Combining the power of JReport bean APIs, and the reusability of the JReport beans, you will not need to open JReport GUI each time to run, print, or diagnose the problems of the report.

tour33.gif (4316 bytes)

tour34.gif (4395 bytes)

Altogether, we provide the following beans or API:

Detailed descriptions of each will follow later in this chapter.

JReport Engine Bean

JReport Engine Bean provides a programming API to the report running and exporting process. JReport Engine is mainly responsible for fetching data qualified from the data source and returning the result to JReport.

Briefly, JReport Engine Bean enables the user to:

Installation

Installing with JReport Designer

When you install JReport Designer, JReport Engine Bean will be installed at the same time. After installation, you should have the main components as below:

lib\JREngine.zip* - Archive file for JReport Engine Bean.
bin\report.ini* - Configuration file.
lib\log4j-1.2.8.jar* - Jar file used for JReport Engine logging system.
lib\JimiProClasses.zip - Non-GUI Engine class library, please append this to the classpath besides JREngine.zip.
lib\resource.zip - Resources of JReport Designer.
lib\xerces.jar - Jar file used when exporting to xml.
lib\JRResultViewer.zip - Archive file for JRResult Viewer Bean.
lib\JRResultViewer.jar - Jar file for JRResult Viewer Bean.
lib\chart.jar - Jar file used when exporting to html with images to be embedded as a chart applet in the html file.
lib\udo\udo.ini - Register of user defined objects.
lib\activation.jar - Jar file used when exporting to mail.
lib\mail.jar - Jar file used when exporting to mail.
lib\Itext.zip - Archive file used when exporting to PDF.
lib\poiHSSF_151.jar - Jar file used when exporting to Excel.
Readme.txt, License.txt - Information about release.
help\pro-material\TestEngineBean.java, TestWherePortion.java, LocalWherePortion.java, TestSunVMMPValue.java, - simple test programs to demonstrate how to call and use JReport Engine Bean. Or you can find them on our Web site at http://www.jinfonet.com/webpage/kbase/kbase.htm for the manual related materials.

Note: The asterisk * for the first three means that when you call JReport Engine Bean, these three files must be used.

Preparation for calling JReport Engine Bean

Before calling JReport Engine Bean, you must make sure that:

  1. Because the only archive file for JReport Engine Bean is JREngine.zip. You need to set the CLASSPATH environment variable before you compile and run the program. Append the following string to the CLASSPATH:
    <JReport_Install_Dir>\lib\JREngine.zip;<JReport_Install_Dir>\lib\log4j-1.2.8.jar.
  2. Beginning with Build 569, before you call the methods for exporting a report to Mail, PDF, Excel or XML format, you should add the corresponding class files or jars with valid path in your classpath.
    a. Mail: mail.jar and activation.jar
    b. PDF: Itext.zip
    c. Excel: poiHSSF_151.jar
    d. XML: xerces.jar
  3. When you set the report home in the bean, JReport will get information from the file report.ini under %ReportHome%\bin and check whether they are valid by setting runtime key in the bean. Open report.ini, you will find the configuration information, including the temp path, template path and the help path. JReport Engine Bean will use the temp path to export the temporary files. Therefore, make sure the temp folder specified in report.ini exists.

Deploying JReport Engine Bean Runtime Components

When you only use the JReport Runtime instead of JReport Designer, you should deploy Engine Bean Runtime components which include the following files:

JREngine.zip - JReport Engine Bean
JRResultViewer.zip - Result Viewer Bean
JRResultViewer.jar - Result Viewer Bean in jar
log4j-1.2.8.jar - Jar file used for JReport Engine logging system
chart.jar - Chart applet
udo.ini - Register of user defined objects
report.ini - Configuration file
activation.jar - Used when export to mail
mail.jar - Used when export to mail

Notes:

  1. report.ini - In your code if you set the reportHome "c:\\jreport", we will read the file report.ini under the directory c:\jreport\bin. You will find in this file the configuration information, including the temp path, template path and the help path. JReport Engine Bean will use the temp path to export the temporary files. Therefore, you should ensure there exists the temp folder specified in the file report.ini.
  2. If you only want to generate a report, you need only JReport Engine Bean, while if you want to view the report result file, you will use JReport Result Viewer Bean. Of course, you will need both beans if you want to accomplish your goals of generating and viewing reports in one instance of a class.

Properties

JREngine Bean has following properties. All the data types of the properties are of Java strings. These properties are listed below:

The following methods are used for value assignment to the above properties:

Where,

Notes:

Programming with JReport Engine Bean

Import the classes of JREngine Bean by adding the following import statements at the beginning of your program. The first import statements bring into the bean class;
import jet.bean.*;
import java.awt.*;
import java.awt.event.*;

Then, we will create an instance. To report with JREngine Bean, you should create an instance of JREngine Bean first.Note: From version 4.0, when you call JREngine Bean in your program, you should set your user id and key of JReport Runtime.

bean = new JREngine();

//From Version 4.0
bean.setUID("JReport Runtime User ID");
bean.setKey("JReport Runtime Key");

After the object is created, set the report home, report file, catalog file, result file (if necessary), parameter values (if necessary).

bean.setReportHome("c:\\jreport");
bean.setReportName("c:\\jreport\\demo\\reports\\DateParameterUsage.cls ");
bean.setCatName("c:\\jreport\\demo\\reports\\Tutorial.cat");
bean.setParamValues("STARTDATE=05/15/1998,ENDDATE=06/10/1998");
bean.setResultFile("c:\\jreport\\temp\\phaseorder.rst");
bean.runReport();


Note: You could run or export a self-contained report by calling JReport Engine Bean. Suppose you want to run a self-contained report "customerlist.clx" which was saved under c:\jreport\demo\reports, you do not need to set the catalog name in your code, you could just set the report home, report file, show debug and error information (if necessary), log file (if necessary) as below:

bean.setReportHome("c:\\jreport");
bean.setReportName("c:\\jreport\\demo\\reports\\customerlist.clx");
bean.setShowInfoLevel( bean.vDebug | bean.vError );
bean.setLogFile("");
bean.runReport();


For more information about Self-contained Report, see User's Guide | JReport Designer Window | Main Menu.

Reference Note: JReport Enterprise Server User's Guide | Clients Accessing JReport Enterprise Server | Report.

With JREngine Bean object, you can manipulate and access many reports. You never need to create a bean for each report. There are a lot of useful methods provided in JREngine Bean, and you can call them before/after runReport() method.

Showing Information

The two properties showInfoLevel and logFile are used for controlling debug, error and other information displayed. The following two methods are used to set values to these properties:

Note:

  1. vDebug, vError and vOff are used for showing debug information, error information and turning off debug and error information.
  2. LogFileName specifies where the debug, error and other information will go. LogFileName contains both the path and the file name. If no path is specified, the current path is used. If no file name is specified, the file jreport.log is used.

Returning Code

The method getStatus() returns a message about the status after runReport() in JReport Engine Bean is called. If it is applied earlier, it will only return "No report load" for that the method just stores static value. The getStatus () method may return one of the following messages:

Exporting To HTML, Mail, PDF, TEXT, XLS, PS, RTF, XML and Fax

There are also several methods with which JReport Engine will export the result file (with the .rst extension) to different file formats (HTML, PDF, TEXT, XLS, PS etc.). The example program TestEngineBean.java will demonstrate how to use them. One method can be implemented by using different parameters. For more information about it, please refer to the JReport Java doc.

Printing Reports

There are four methods provided for printing the report:

Parameters:

Note:

  1. The first method printReport ( ) is called to start printing. It will take the third method using the default parameter values like this:
    printReport(null, null, true, false, false, false)
  2. The second and third method allows you to pass the parameters -- printJob, pageFormat, bInteractive, bInbackground, bUseJDK11 and bSeparateLargePage.
  3. The third printing method (with the bSeparateLargePage parameter) is not recommended, it may cause some unexpected errors, for example, you may get an extra blank page.
  4. After printing is started, the method getPrintStatus ( ) can be used to get the print job status. Returned values of getPrintStatus ( ) are:
    "No print job"
    "Busy"
    "OK"
    "No report load"
    Other error messages if there are errors.

Example1: Under JDK1.2 or higher, if you use JDK1.2 printing method (boolean bUseJDK11), you can call the printReport method like this:
PrinterJob printJob = PrinterJob.getPrinterJob();
bean.printReport(printJob, printJob.defaultPage(), false, false, false);
Or, if you do not want to getPrinterJob, simply call:
bean.printReport(null, null, false, false, false);

Example2: Under JDK1.2 or higher, if you use JDK1.1 printing method, you are best recommended not to getPrintJob, just call:
bean.printReport(null, null, false, false, true);

Example 3: Under JDK 1.2 or higher, if you use JDK1.1 printing method and select a network printer, you can call the printReport method like this:
bean.printReport(null, null, false, false, true, false, "job1", "\\\\GUOF\\HP LaserJet 6L Pro PCL5e");

Example 4: Under JDK 1.2 or higher, if you use JDK1.1 printing method and select a local printer, you can call the printReport method like this:
bean.printReport(null, null, false, false, true, false, "job1", "HP LaserJet 6L Pro PCL5e");

WHERE Portion

Also JReport Engine provides the methods to add, delete, save and get a new WHERE portion in the catalog. Please note that the the join relationships of tables will remain in the new where clause. By specifying the name of the WHERE portion, you can pick it out from report catalog and bind it up with the current query:

Parameters:

Data Driver

The setDataDriver() method is used to specify the user data source driver. JReport can use user data source driver as the data source of a report. By default, JReport uses JDBC connection. Only when the report works with the user data source can users call this method.

Note: This method is mutually exclusive with the method of setResultSet(). Users can only use one of them at the same time.

Parameter:

Cached Query Result

The setResultSet() method is used to set the cached query result to work with JReport. When this method is called, JReport will load the specified cached query result and generate reports with data from the cached query result.

Note: This method is mutually exclusive with the method of setDataDriver(). Users can only use one of them at the same time.

Parameter:

National Language Support (NLS)

JReport products support the National Language feature. If you specified to apply NLS, when you design and save the report, the language-dependent text of Label object will be extracted to a resource file(.properties). Copy the resource file for another language and modify the text in the file. When JReport is running, JReport Engine will retrieve the language-dependent text according to the current locale, the end user will get a report result that matches his locale setting.

Notes:

  1. At run time, you can specify the encoding and Locale for rendering the report result accordingly. But please make sure that when you design the report, you have set it to support NLS and have made the property file for the language you hope to apply.
  2. In addition, we also provide the following method that might be very useful.
    Vector getAvailableLocales(String clt)
    This method will get all of the Locales that current report supported. The parameter clt is current client's Locale. If clt is in current report Locales it is moved to the index at zero.

Getting the Communicator of this report

The Communicator here is a class defined by JReport. This method will launch to run JReport Engine Bean, but do not save to the result file. It returns the Communicator of this report.

You are recommended to use this method in JReport Engine Bean and setCommunicator() in JReport Result Viewer Bean. That is,
resultViewerBean.setCommunicator( engineBean.getReportCommunicator() );

Modifying User Information

Obviously, this method is to modify user's information: user ID and password.

Setting Connection Information

Parameters:

This method enables users to set the connection information before running the report. You can let the user specify the user id and the password before running a report to ensure the security. Another application of this method is that readers can select a different database before running reports, so they can see different report results. Of course, usually in this case, the two databases have the same structure and this will ease the work of building another catalog.

For example, this method may be called like this:
setConnection("jdbc:Oracle:thin:@204.177.148.30:1521:orcl","scott","tiger","oracle.jdbc.driver.OracleDriver");

Setting Result Set

Parameter:

This method is used to set the result set required to run the report.

For example, this method may be called as below:

Class.forName("oracle.jdbc.driver.OracleDriver");
Connection connection=DriverManager.getConnection("jdbc:oracle:thin:@222.222.222.45:1521:orcl815","System","manager");
Statement stmt = connection.createStatement();
ResultSet rs = stmt.getResultSet();
bean.setUserResultSet(rs);

Getting the Version Number of JReport Engine Bean

This method will get the version number of your Engine Bean.

Example: you can use this method like below:
bean = new JREngine();
System.out.println(bean.getVersion());
Then the method will print out:
JReport Engine Bean version : 3.1.1; Build Number : 512; Help Version : 505
The Help version is the matched help version number of the current engine. The two may be different.

Getting Page Orientation

The method getPageOrientation is used for getting the orientation of the report page. You should call this method after calling runReport method. The return value is an int value, and it can be LANDSCAPE or PORTRAIT. If it is -1, it makes no sense, say you may have called it before calling runReport method, which is wrong.

Getting DBField Information

The method is used to get the information of all DBFields in the Detail section, including DBFields in the Detail section of the subreport which is inserted in the Detail section. The method returns a vector which contains name, type and SQL type of DBFields.

Note: The method will return DBField information whatever the Detail section is invisible or suppressed.

Getting Report Information

The method is used to get the information of reports, including record number, total page number, print time, username.

Note: Before this method is used, method runReport( ) or loadReport( ) should be called first.

Single Thread

The above method checks whether the current engine is single-threaded. The returned value is of boolean type. If the current engine is single-threaded, it will return true, otherwise false.

The above method can be set to to run the engine with a single thread. It is specially used in the environment like EJB which only allows single thread when doing any transactions.

Parameters:

Run-time Key

Beginning with version 4.0, when you call JReport Engine Bean in your application program, your user ID and runtime Key are needed.

Parameters:

The Illustrative Example

After you installed JReport Engine Bean, you will find the illustrative test programs under %installroot%\help\pro-material. Or you can go to our web site at http://www.jinfonet.com/webpage/kbase/kbase.htm for the manual related materials.

TestEngineBean.java - a test program. Let us explain how TestEngineBean.java works, and how it uses the methods provided by JReport Engine Bean mentioned above. First, the example file TestEngineBean.java contains some hard-coded paths. These must be modified before they can be compiled and run. For example, assuming JReport Designer is installed under d:\jreport, then the "Test A" section can be modified to the following:

bean.setUID("test");
bean.setKey("ffffffffffffffffffffffffffffffffffffffff");
bean.setReportHome("d:\\jreport");
bean.setReportName("d:\\jreport\\Demo\\Reports\\GroupingWithFormulas.cls");
bean.setCatName("d:\\jreport\\Demo\\Reports\\Tutorial.cat");
bean.setResultFile("d:\\jreport\\temp\\ GroupingWithFormulas.rst");

The result file will be saved under the d:\jreport\temp directory and the result file name will be GroupingWithFormulas.rst. In addition, TestEngineBean.java will also show how to use JReport Engine to export result file (with the .rst extension) to different file formats (HTML,PDF,TEXT,etc.). Assuming the GroupingWithFormulas.rst has already been generated by JREngine, now we export it to different file formats:
bean.exportToPdf("d:\\jreport\\temp\\ GroupingWithFormulas_0.pdf");
bean.exportToText("d:\\jreport\\temp\\GroupingWithFormulas_0.txt", true);
bean.exportToHtml("d:\\jreport\\temp\\GroupingWithFormulas_0.html");

d:\\jreport\\temp\\... is the location where users specify the new generated files. At last, TestEngineBean.java will call the methods to add, delete, save and get the WHERE portion in the report catalog:
bean.saveWherePortion("condition2","@\"Customers_Customer ID\" < 20");
bean.setNamedWherePortion("condition 2");
bean.setWherePortion("((@\"Customers_Customer ID\" > 10) and (@\"Customers_Customer ID\" < 20))");
bean.deleteWherePortion("condition2");
bean.getAvailableQueryFields();
bean.getAvailableWherePortions();

To run the TestEngineBean.java, use the following command to compile the test program first:
javac -classpath d:\JReport\lib\jrengine.zip;d:\JReport\lib\log4j-1.2.8.jar; TestEngineBean.java

Here we assume d:\JReport is the place where JReport Engine is installed and it is the current directory when users execute these commands. Finally, the test program can be run with the following command:
java -classpath d:\JReport\lib\jrengine.zip;d:\JReport\lib\log4j-1.2.8.jar; TestEngineBean

When the test program is complete, you will note a temporary file <reportname>.rst. In this test program, this will be either customerlist.rst or phaseorder.rst depending on which report has been executed. These result files can be read and displayed by either JReport Viewer (the thin client viewer) or JReport Result Viewer Bean.

TestWherePortion.java - A test program purely for the method operated on WHERE Portion. You can add, save and delete new WHERE portion just like what we do in TestEngine.java. The difference is that the user can do all these things in his own report home, catalog and the report file. These result files can be read and displayed by either JReport Viewer (the thin client viewer) or JReport Result Viewer Bean.

Index