Index

JReport (Client) Viewer Bean

In order to make the Viewer easily embedded in your Java applications, JReport Viewer is now also available as a Java Bean. JReport Viewer Bean can send a request from a client workstation to run and view reports on JReport Enterprise Server.

Briefly, JReport Viewer Bean enables one to:

Note the difference of JReport Viewer Bean (JRClient Viewer Bean) and Result Viewer Bean (JRResultViewer Bean), JRResultViewer Bean is used to view local JReport result files in the standalone mode, while JRClient Viewer Bean is to connect with the server in the server/client mode.

Reference Note: JReport Enterprise Server JavaDoc jet.bean package. You can go to http://www.jinfonet.com/docs.htm to browse the file online. The Java source code used in this page can also be found.

Installation

There are separate zip files for Viewer Bean posted on our Web site http://www.jinfonet.com/download.htm.
Please download the file JREntVBean.zip (for JReport Enterprise Server). We provide other versions of viewer bean for swing 1.1 (JREntVBeanSwing11.zip) and for swing 1.0 (JREntVBeanSwing10.zip)

The JREntVBean.zip file includes the following files:

Two Approaches of Invoking JRViewer Bean

The two approaches of invoking JReport Viewer Bean are described in the following sections.

Invoking Viewer Bean without Supplying Report Parameters

In this approach, your Java application calls Java bean JRDirectViewer and provides the following properties:

When Java bean JRDirectViewer is loaded, it will ask JReport Enterprise Server to run the report and pop up a dialog on the screen to ask you to input report parameters if they are required by the report. This approach has the advantage of not requiring your Java application to provide the report parameters. The disadvantage is that it will display a dialog on the screen for you to enter parameter values.

Note: The catalog name and the report name must have file extensions (such as .cat or .cls). The catalog name must be a full path name which is relative to the server's root directory in the resource tree, and since v6.0 it is recommended that the report name is also a full path name. If you access the JReport Enterprise Servlet, you must set the servlet path also, for example:

JRDirectViewer.setFullPath("/Jinfonet_Sybase/JReport");

For the catalog name and full path string, the first character must be '/', and the last character must not be '/'.

Invoking Viewer Bean with Report Parameters

The second approach of invoking JReport Viewer Bean has two passes: the first pass obtains information about the parameters required by the report and the second pass submits the required parameters. If the user's Java application already knows the required parameters, the first pass may be eliminated. In this approach Viewer Bean will not display any dialog on the screen. Your Java application retains the full control to the screen and is responsible for submitting all the required report parameters.

Pass one:

Your Java application calls the Java bean JRPrepareViewer with the following properties:

JRPrepareViewer returns a vector containing the information about the report. The method getReportParams ( ) should be called after calling JRPrepareViewer to obtain the vector. The size of the vector is the number of the parameters needed by the report, which can be obtained from the method size(). Each element in the vector contains the type of a parameter, which can be obtained using the method getType ( ). The possible parameter types are listed below:

Note: While using Prepare Viewer Bean in JReport Enterprise Server, if you want to show the parameter dialog and modify the parameter value in this dialog, you can call the method

setPopupParamDialog( true/false )

where, "true" means the parameter dialog will pop up.

Pass two:

In the second pass your Java application prepares the parameters based on the information provided by the vector. It then calls Java bean JRRunViewer with the following properties:

Notes: Parameters -- The string contains the parameter values, separated by commas (',').If more than one parameter is needed in the report, you can pass multiple parameters in the paramValues string. The ValuesString format is: paraName1=paraValues1, paraName2=paraValue2 where the paraName1 and paraName2 are the parameter names and paraValue1 and paraValue2 are the values. The comma is the separate operator, and the equal sign is to separate the parameter name and parameter value. If the parameter name or parameter value contains the separate operator -- comma or equal sign, it needs escape. We provide the escape operator \\. If the escape operator is put before the separate operator, we will not treat it as the separate operator. For example:

Note: You do not necessarily set the values for all the parameters. If you do not set a parameter value, JReport will use the default value for this parameter.

Load Viewer Bean from an URL or RandomInputable directly

This assumes you have your own server, and build this server with the Engine of JReport Enterprise Server. If you want to load the viewer to view the result file generated in the server side, and you do not want to transport the result file directly, you can use the following methods:

* If your server and client use the HTTP protocol to communicate, then you can call the method setURLAddress("URL address") in JReport Viewer Bean, the URL must be the qualified result file generated using the Engine in the server side. The code is like this:

JRRunViewer viewerBean = new JRRunViewer();
viewerBean.setURLAddress("the url address");
viewerBean.runReport();

* If your server and client do not use the HTTP protocol to communicate, then you can call the method setRandomInput in JReport Viewer Bean. This method has one parameter, it is an instance of interface RandomInputable (see RandomInputable.java and RandomAccessable.java), this interface defines how to transport the result file generated by JReport Engine Bean in the server side to the client side. You must define a class which implements all methods in the interface RandomInputable, and then pass this class's instance to the method setRandomInput as the parameter. The code is like this:

JRRunViewer viewerBean = new JRRunViewer();
viewerBean.setRandomInput("the class which implement interface RandomInputable");
viewerBean.runReport();

We also provide a class which has already implemented the interface RandomInputable, if you do not want to write a new class, you can use it. The class is named jet.ie.io.RAStreamInput. It has one constructor:

public RAStreamInput(InputStream in, long totalLength) throws IOException

The first parameter is the input stream opened by the connection, the second is the stream's length. See an example hereTestRAStreamInput.java.

Note: In this case, you do not need to set other properties of JReport Viewer Bean. In addition, if the server needs to check permission for login, you must do this action before calling JReport Viewer Bean.

Get Page Orientation

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

Export to Multiple File Formats

There are several methods with which JReport Viewer Bean can export the report result to different file formats (.html, .pdf, .txt...):

The parameters above are explained below:

Where Portion

JReport Viewer Bean provides the methods to add, delete, save and get a new WHERE clause in the SQL query (we will provide the last three methods in the future).Please note that the join relationships of tables will remain in the new where clause. By specifying the name of this new WHERE clause, users can pick it out from the catalog:

The parameters above are explained below:

Showing a Report in a New Frame

While viewing a report, if you want to show a report in a new frame that is different from your application window, call the method setViewInNewFrame( true/false ) in JRDirectViewer or JRRunViewer. "True" means a report is shown in a new frame.

Proxy Setting

If you use JReport Viewer Bean to access JReport Enterprise Server through a proxy, you should set the proxy with the following methods:

If the proxy server needs to be authenticated, you can set the userName and password with the following methods:

Printing a Report

There are four methods provided for printing a report:

The first method printReport ( ) is called to start printing. It will take the last method using the default parameter values like this: printReport(null, null, true, false, false, false)

The second and third method allows you to pass the parameters -- printJob, pageFormat, bInteractive, bInbackground, bUseJDK11 and bSeparateLargePage. Below is the explanation ssof each parameter:

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);

After the printing is started, the method getPrintStatus ( ) can be used to get the print job status. The returned values of getPrintStatus ( ) are:

Browsing Report Pages

These two methods will return the current page number on the screen and the total number of pages of the current report. These two methods can be called only after you have called the method JRDirectViewer or JRRunViewer.

This method will bring the page specified by the pageNumber on the screen. If the pageNumber is out of the range of the current report, the first page (if the pageNumber is less than 0) or the last page will be shown on the screen and the returned value is the current page number.

These four methods will bring the page specified to the screen. The return value of these methods are strings. The value could be:

Zooming a Report Result

If you want to zoom a report result, the zoom( ) method can satisfy your requirement.

zoom(ratio)

The parameter ratio is of integer type, it stands for a percentage value. If you want to enlarge the report to two times the original size, you can call this method:

zoom(200)

If you want to reduce the report size by half, you can call this method like this:

zoom(50)

To see an example, please refer to Sample2.java and Sample3.java.

Set Connection Information

setConnection (String strURL, String strUID, String strPSWD, String strJdbcDriver)

Where,

This method is for JRRunViewer and JRDirectViewer, which enables the user to set the connection information before running the report. You can let users 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 repeatedly.

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");

ClickActionListener

When you click a field in the viewer, you can get the entire record of that field. We have an interface in package jet.thinviewer named ClickActionListener, which can implement this function. This interface is defined like this:

interface ClickActionListener
{
void clickOnField(jet.connect.Record currentRecord);
}

If you have a class A which wants to listen to the click event of the field, then this class can implement this interface. Then after you instantiate a bean, you add this ClickActionListener to the bean (Note: this action must be implemented before running the report). Finally after the report has been shown and you click on a field, we will call the ClickActionListener's method clickOnField, and you will get the values of all columns in that field from the parameter currentRecord.

To see an example, please refer to Sample2.java and Sample3.java.

Logging out from the Server

After viewing the report, if you do not need to access JReport Enterprise Server again, you can log out from JReport Enterprise Server to terminate the connection with it.

Note: When you turn pages in JReport Viewer Bean, JReport Viewer Bean needs to access JReport Enterprise Server later. In this case, you should not call the method logout().

Exiting the Bean

exit ( ) should be called when you want to quit from the JReport Viewer Bean. This method will do some cleaning up work such as deleting temporary files and release resources. It is important, so do not to forget to call this method.

Exposing the whole JReport Viewer's GUI

JRClientViewerBean exposes the whole JReport Viewer's GUI to a new frame. If you want to use the JReport Viewer's GUI and start JReport Viewer in a new frame, you can use this bean.

With this approach, your Java application calls the Java bean JRClientViewer and provides the following properties:

The Report Home is the home path of JReport Client Viewer where the report.ini file and other JReport Client Viewer system files exist. (Note: Up to now, we have only provided JRClientViewer for JReport Enterprise Server.)

National Language Support (NLS)

JReport products support National Language feature. When you design and save a report, the language-dependent text of Label object will be abstracted 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 the report result that matches his locale setting.

For JRCltPreViewer.java and JRPrepareViewer, you can set language and convert to a Locale object.

For JRDirectViewer and JRRunViewer,

At run time, clients can specify the encoding and Locale for rendering its report result accordingly. But please make sure that when you design the report, you have set to support NLS, also you have generated the property file for the language you hope to use.

Returned Code

The method getStatus ( ) should be called each time after calling the Viewer Java Beans. The return string "OK" means the request is accepted otherwise an error message will be returned.

Show Information

The two properties showInfoLevel and logFile are used for controlling debugs, errors and other information display. The following two methods are used to set values to these properties:

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

Set Temporary Path

setTempPath("TempPath")

When JReport Viewer Bean is running, it will generate some temp files. The above method setTempPath() is designed for setting the temp path. If no temp path is set, the temp file will be written to the directory where the application runs.

Example,
setTempPath("c:\\temp");

Modifying User Information

modifyUserInfo(String strUserName, String strPassword)

This method is for JRDirectViewer and JRRunViewer. Obviously, it is to modify user's information: user ID and password.

Illustrative Examples

The example programs Sample1.java and Sample2.java illustrate how to call JReport Viewer Java beans. The example program TestClientViewer.java shows how to call JRClientViewer Bean. Please refer to it for details.

  1. Launching the server which is of the same version of the viewer bean.
  2. Modify the sample code to set the server host name, port number, catalog file etc according to your actual environment.
  3. Compile and run your code calling the bean. When you call one-step viewer bean, only add in your classpath of OneStepJRViewer.jar and log4j-1.2.8.jar, and when you call two-step viewer bean, only add in your classpath of TwoStepsJRViewer.jar and log4j-1.2.8.jar. If you find any problems, you can try archive file JRViewer.zip together with log4j-1.2.8.jar, which can be used in both the circumstances no matter whether it is for the one-step or two-step viewer bean.

Index