Using JReport Engine as a Bean

The JReport Engine Bean (JREngine) and JReport Express Engine Bean (JRXEngine) are intended for users who want to call the JReport Engine from their Java applications to generate the report result file.  The report result file could be viewed by either JReport Viewer (the thin client viewer) or JReport Result Viewer Bean or JReport Express Result Viewer Bean.  Note that this is a direct call interface and it is assumed that both the Java application and the Engine Bean are located on the same computer.

Installation

JReport Engine Bean Installation

JReport Engine is presently available as an executive file EngBeanSetup.exe. After the installation, the user should have some main components as below:

• lib\JREngine.zip - the JReport Engine Bean class library.
• lib\jrviewer.zip - the JReport Result Viewer Bean class library.
• lib\JRResultViewer.jar - the JReport Result Viewer Bean class library in jar format.
• Readme.txt, License.txt - contain information about the release.
• TestSunVMEngineBean.java, TestMsVMEngineBean.java, TestWherePortion .java - three simple test programs to demonstrate how to call and use the Engine Bean , for the detail of them, please refer to The Illustrative Example.  EngineClass.htm, RstViewerBeanUsage.htm, ResultViewerClass.htm - three help files contain information about the JReport Engine Bean and JReport Result Viewer Bean.

JReport Express Engine Bean installation

JReport Express Engine Bean is packed inside the JReport Express Edition package. After the installation of JReport Express Edtion, there are several JReport Express Engine Bean files under the %installroot%\lib driectory. Those files are:

• lib\JRXShare.zip -  the shared class library of the JReport Express Engine Bean and JReport Express Result Viewer Bean.
• lib\JRXEngine.zip - the JReport Express Engine Bean class library.
• lib\JRXViewer.zip - the JReport Express Result Viewer Bean class library.
• lib\resource.zip -  the resource library of the JReport Express Engine Bean and JReport Express Result Viewer bean.
• TestJrxEngineBean.java - This is a Java program for demonstrating how to call and use Engine Bean. For the detail of it, please refer to The Illustrative Example.  EngineClass.htm, RstViewerBeanUsage.htm, ResultViewerClass.htm   - three help files contain information about the JReport Express Engine Bean and JReport Express Result Viewer Bean.

The following sections give further details about the JReport (Express) Engine Bean. When you compile and run your application that calls the engine bean,you should  be sure that the class path settings (which is required by the Javac.exe and Java.exe) contains the JDK 1.1.6,1.17 or 1.2 classes.zip and JREngine.zip (or JRXEngine.zip , JRXShare.zip and resource.zip).

JREngine Properties

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

• reportHome -- The home path where the report.ini and other JReport system files exist.
• reportName -- 'The report name which the engine will run.
• catName -- The name of the catalog which contains all the required objects used in the report.
• paramValues -- The string containing the parameter values, separated by comma (',').
• paramFile  -- The name of the parameter value file.  This will be ignored if paramValues is specified.
• resultFile - The name of the result file.

Note that the reportName is a string which contains both report path information and the report name.  The catName is also a string which contains both catalog path information and the catalog name.  The report path and the catalog path may be different.  The resultFile contains both the path and the file name information.  If there is no path specified, the current path is used.  If there is no file name specified, the reportName is used (with the .rst extension).  If there are more than one parameters needed in the report, you can pass multiple parameters in the paramValues string.  The format is: paraName1=paraValues1,paraName2=paraValue2 where the paraName1 and paraName2 are the parameter names and paraValue1 and paraValue2 are the values.

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

• setReportHome ("HomePath")
• setReportName ("ReportName")
• setCatName ("CatalogName")
• setParamValues ("ValuesString")
• setParamFile ("ParamFileName")
• setResultFile ("ResultFileName")
• runReport( )

The method called runReport ( )  will have the same effect as setLoadReport ("yes").  setLoadReport ("yes/no") is the method in the last Engine Bean version.

If you do not want to run report, but want to know the report's parameters, you can call method getReportParams().  This method will return a vector and  each element of this vector is jet.formula.ParamDesc.  The class ParamDesc has five public properties:

• name - parameter name, this property is String type
• type - parameter type, this property is String type
• promptText - parameter prompt text, this property is String type
• value - parameter value, this property is String type
• isColumn - indicate whether this parameter must be a DB column name or  is a boolean type.  If  this parameter is a DB column name, this parameter's value must be a available group field.  You can call method getAvlGroupFields(), the method will return a vector which contains all available group fields. Note: If having more than one parameter is a DB column name, these parameters value can not be same.

There are also several methods with which the JReport Engine will export result file (with the .rst extension) to different file formats (HTML, PDF, TEXT etc.).  The example program TestSunVMEngineBean.java will demonstrate how to use them:

The parameters above are explained below:

• ResultFileName -- The name of the result file which you want to convert to the required format.
• HtmlFileName -- The name of the HTML format result file with the full path.
• PdfFileName -- The name of the PDF format result file with the full path.
• TextFileName -- The name of the TEXT format result file with the full path, "true/false" is to set whether this text file is a  normal text format or a  Standard Data Format (the standard data format text file is the text file that each row of it represents each record in the report. It can be used as a text data source to exchange data with other applications). 
• The delimiter is a character which will be used in SDF(Standard Data Format) format.  The delimiter will be used only when the "true/false" parameter is set to be  false.  A delimiter could be a ',' (the CSV format) or any other character.   The default is ' ' (a blank), that is, the SSV format.

Note: All the above export methods are not available in JReport Express Engine bean.

Also JReport Engine provides the methods to add, delete, save and get a new WHERE portion in the catalog.  By specifying the name of the WHERE portion,  users can pick it out from report catalog easily and bind it up with the current query:

• setNamedWherePortion(queryName) -- Sets a named WHERE portion from the catalog to the query of the current report, if this WHERE portion can not be found in the catalog, simple return to the" false".
• setWherePortion(WherePortionString) -- Sets the WHERE portion in the string format to the query of the current report.
• saveWherePortion(queryName,WherePortionString) -- Saves the WHERE portion in string format with the specific query name in report catalog.
• deleteWherePortion(queryName) -- Deletes a specific WHERE portion from report catalog, updates and saves the catalog after the delete.
• getAvailableQueryFields() -- Gets the available query fields from the query for the current report, this will return an enumeration of the names of fields, formulas and parameters and  their corresponding data type which will be needed to build up the WHERE portion and validate the conditional.
• getAvailbleWherePortions() -- Gets an enumeration of the names of all the WHERE portions saved in the report catalog.
• SaveCatalog() -- Saves the current catalog.  Returns to the" true" if successfully saved.

The parameters above are explained below:

• queryName -- The name of the WHERE portion in SQL query.
• SQL -- the specific WHERE portion.

Note: All the above WHERE portion methods are not available in JReport Express Engine bean.

The method addFileQuery provides for adding the file query (customer query) to the current catalog:

• AddFileQuery(strName, fileName) -- Adds the file query specified by the fileName to the current catalog.

The parameters above are explained below:

• strName -- The name of file query in the catalog.
• fileName -- the name of the SQL file.  (The SQL file is the file which contains a SQL statement.)

Note: The above AddFileQuery method is not available in JReport Express Engine bean.

Show information

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

• setShowInfoLevel (vDebug/vError/vOff)
• setLogFile ("LogFileName")

vDebug, vError and vOff are used for showing debug information, error information and turning off debug and error information.  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.

Return Code

The method getStatus () returns a message about the status after JReport Engine Bean JREngine is called.  The getStatus () method may return one of the following messages:

• "OK"
• "Error: Cannot find the resource file JRsIndex.jrc!"
  This is caused by the incorrect setting of the report home path.
• "Error: Cannot open the catalog "Catalog Name"!"
  The JREngine cannot open the given catalog file.
• "Error: Cannot open the report "Report Name"!"
  The JREngine cannot open the given report file.
• "Error: Cannot open the parameter file "Parameter file name"!"
  The JREngine cannot open the given parameter file.
• "Error: Unknown format in Parameter values!"
  The parameter values string has the wrong format.
• Other errors.
  The JReport engine bean encountered other exceptions.

The Illustrative Example

1. TestMsVMEngineBean.java

TestMsVMEnginebean.java is the test program based on the Microsoft Virtual Machine, TestSunVMEnginebean.java is the test program based on the Sun Virtual Machine.  we will focus on  later to explain how JReport Engine Bean works.

2. TestSunVMEngineBean.java

Let us explain how TestSunVMEngineBean.java works step by step, and how TestSunVMEngineBean.java uses the methods provided by JReport Engine Bean which we mentioned above.  First, the example file TestSunVMEngineBean.java contains some hard-coded paths.  These must be modified before they can be compiled and run.  For example, the following paths need to be changed for the "Test A" section:

bean.setReportHome("d:\\jr");
bean.setReportName("d:\\jr\\Report\\SunVMDemo\\Tutorial\\customerlist.cls");
bean.setCatName("d:\\jr\\Report\\SunVMDemo\\Tutorial\\Tutorial.cat");
bean.setResultFile("d:\\jr\\temp\\customerlist.rst");

Where d: should be replaced by the drive and jr should be replaced by the directory that you installed the JReport Workbench.  The result file will be saved under the d: drive root directory and the result file name will be customerlist.rst. Second, TestSunVMEngineBean.java will also show how to use JReport Engine export result file (with the .rst extension) to different file formats (HTML,PDF,TEXT,etc.).  Assuming the customerlist.rst has already been generated by the JREngine,  now we export it to different file formats:

bean.exportToPdf("d:\\jrebean\\temp\\customerlist_0.pdf");
bean.exportToText("d:\\jrebean\\temp\\customerlist_0.txt", true);
bean.exportToHtml("d:\\jrebean\\temp\\customerlist_0.html");

d:\\jrebean\\temp\\... is the location where the user specified for the new generated files. At  last, TestSunVMEngineBean.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 TestSunVMEngineBean.java, you can use the following command to compile the test program:

javac -classpath c:\java\lib\classes.zip;d:\JREbean\lib\jrengine.zip; TestSunVMEngineBean.java

Here we still assume d:\JREbean is the place where the JReport Engine is installed and it is the current directory when you execute these commands.. Finally, the test program can be run with the following command:

java -classpath c:\java\lib\classes.zip;d:\JREbean\lib\jrengine.zip;  TestSunVMEngineBean

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

3. TestWherePortion.java

TestWherePortion.java is a test program purely for the method operated on WHERE Portion, you can add, save and delete new WHERE portion just the same as we do in TestSunVMEngine.java, the difference is that the users can do all these things in his own report home, catalog and the report file.

4. TestJrxEngineBean.java

TestJrxEngineBean.java shows you how to use the methods provided by JReport Express Engine bean which we mentioned above, and explains how it works step by step.  First, TestJrxEngineBean.java contains some hard-coded paths.  These paths must be modified before they can be compiled and run.  For example, the following paths need to be changed:

1)You should change global variable for the example file.

String homePath = "c:\\jrexpress"; //Set the root that JReport Express Engine be installed.
String reportPath = homePath + "\\Demo\\reports\\interbase\\";//Set the path that current report exists.
String resultPath = homePath + "\\temp\\";//Set the path for result files.

2)Change the following paths for the "Test A" section. It  mainly tells you how to make the report engine run.

bean.setReportHome(homePath);
bean.setReportName(reportPath + "customerlist.cls");//Set the report name which the engine will run.
bean.setCatName(reportPath + "Tutorial.cat");//Set the name of the catalog which contains all the required objects used in the report.
bean.setResultFile(resultPath + "customerlist.rst");//Specify the name of the result file which will be generated by Engine.

3)Change the following paths for the "Test B" section. It  mainly tells you how to use setParamValues(String) method.

bean.setReportHome(homePath);
bean.setReportName(reportPath + "phaseorder.cls");
bean.setCatName(reportPath + "Tutorial.cat");
bean.setParamValues("STARTDATE=1998-05-15,ENDDATE=1998-06-10");//Set the parameter values of the report.
bean.setResultFile(resultPath + "phaseorder.rst");

4)Change the following paths for the "Test C" section. It  mainly tells you how to use setParamFile(String) method.

bean.setReportHome(homePath);
bean.setReportName(reportPath + "invoice.cls");
bean.setCatName(reportPath + "Tutorial.cat");
bean.setParamFile(reportPath + "invoice.param");//Set the name of the parameter value file.
bean.setResultFile(resultPath + "invoice.rst");

To run the TestJrxEngineBean.java, you can use the following command to compile the test program:

javac -classpath d:\java\lib\tools.jar;d:\java\jre\lib\rt.jar;c:\jrexpress\lib\JRXShare.zip;c:\jrexpress\lib\JRXViewer.zip;c:\jrexpress\lib\JRXEngine.zip;c:\Jbuilder3\lib\swingall.jar;   TestJrxEngineBean.java

Here we still assume c:\JRExpress is the place where the JReport Express Engine is installed and it is the current directory when you execute these commands. If you run the report for interbase user, you must add classpath "C:\Program Files\InterBase Corp\InterClient\interclient.jar", or delete it from classpath. Finally the test program can be run with the following command:

java -Djava.compiler=NONE -classpath d:\java\lib\tools.jar;d:\java\jre\lib\rt.jar;c:\jrexpress\lib\JRXShare.zip;c:\jrexpress\lib\JRXViewer.zip;c:\jrexpress\lib\JRXEngine.zip;c:\jrexpress\lib\resource.zip;c:\Jbuilder3\lib\swingall.jar;"C:\Program Files\InterBase Corp\InterClient\interclient.jar"; TestJrxEngineBean

These result files can be read and displayed by either the JReport Viewer (the thin client viewer) or the JReport Express Result Viewer Bean.