RReport Visual Builder (com.java4less.rreportVB)

Introduction

RReport will assist you in the task of creating reports for you Java [TM] applications. This report can use JDBC[TM] drivers to access a database and retrieve the data to be printed. However this is only one of the possibilities, you can also programatically print the report and set the values yourself, or print data form an array or JTable.

The product is made of:

  1. RReport Visual Builder: this is the environment you will use to design the reports. The classes for this product are include in the package com.java4less.rreportVB.
  2. RReport: this is the runtime library you will use in your Java[TM] application in order to print the report you have previously designed. The classes for this library are included in the package com.java4less.rreport.

Note: the present document covers RReport Visual Builder which uses the RReport library. It is assumed that the reader has some background about the RReport package. Please read also RReport Documentation .

 

Requirements

RReport Visual Builder requires Swing. The runtime version (RReport) however does not require Swing. If you are however developing a Swing application you can use a Swing preview Window (RReportJWindow).


Both, the builder and the runtime version will run with the Java Development Kit 1.1 or newer.

 

Distribution of applications

In order to distribute your application that includes reports you must distribute the following package:

You DO NOT need to distribute:

 

Starting the Visual Builder

In order to run the Builder and start designing your reports you need to execute the following commands:

or you can just run the batch files runMS.bat and runSUN.bat respectively.

If Swing.jar is not available in your computer, you can download it from the following locations:

Note: Java Development Kit 1.3 and later do not require any additional Swing file since it is included in the java runtime.

 

Description of the screen

The screen of the builder is very simple, it has three main parts:

Futhermore the toolbar will allow you to perform this operations (buttons from left to right):

 

screenshot 1

By clicking on the name of the Area its properties will be displayed in the properties window.

 

The properties window

The properties window will display the properties of the selected object, area or report. Click on refresh if you want to see the result of the modified properties.

 

Working with objects

Adding a new object

In order to add a new object you must select the appropiate object in the toolbar and click on the area you want to add the object. Select the first button in the tool bar (the one with the pointer) in order the deactivate the current selection.

Selecting one or more objects

Click on the objects in order to select them. Selected objects show four black squares on the corners. In order to select more than 1 object you must press the SHIFT key and click on the objects.

Deleting objects

Use the CTRL-X or DEL in order to delete selected objects

Moving objects

Move selected objects by dragging and dropping them.

Resizing objects

Move the cursor to the right or the bottom border of the objects in order to resize them. The cursor will the will change and you can drap the border of the object.

Copying objects

Copy selected object with CRTL-C and paste themin the curret area with CRTL-V. You can also use the menu items in the Objects menu or in the popup menu.

Aligning objects

Select the objects you want to align and click on the right button of the mouse. Select then the alignment type from the popup menu.

Bringing object to the front or to the back

you can determine the order in which objects are printed by bringing them to the front or the back. Select the objects you want to move and click on the right button of the mouse. Select then the action (bring to front or send to back) from the popup menu.

 

Description of the supported objects

Report

Select File-> Properties to set the properties of the report. The properties are:

Area

Click on the area's name to set the properties of the area:

 

RVObject

This object corresponds to the RObject object used in RReport. Itsproperties are common for all the object used in report. The properties are:

 

RVField

This object corresponds to the RField object used in RReport. It is used to print texts and its properties are:

RVCheck

This object corresponds to the RCheck object used in RReport. It is used to boolean values and its properties are:

RVCombo

This object corresponds to the RCombo object used in RReport. It is used to display values based on the value of a key, its properties are:

RCombo support also a list of images aqs values to be printed but RVCombo only support a list of strings. If you want to specify a list of images you should do it programatically when you run your report. For example:

report.importFile(filename);
RCombo combo=(RCombo) report.getAreaByName(areaname).getItemByName(comboname);
combo.Values=listOfImages;

See Running the report

 

RVPicture

This object corresponds to the RPicture object used in RReport and is used to print images. Its properties are:

 

RVLine

This object corresponds to the RLine object used in RReport. Its properties are:

 

RVPageBreak

The RPageBreak will force that a page break after the area is printed.

 

RVRectangle

This object corresponds to the RRectangle object used in RReport. Its properties are:

 

RVUserObject

This object corresponds to the RUserObject used in RReport. It is used for printing your own RObject.

 

RVBarcode

This object will insert a barcode in your report. Note that a separater license of RBarcode is required if you want to print barcodes. RReport includes a evaluation version of RBarcode.

The parameters of the barcode are explained in RBarcode's documentation.

 

RVGraph

This object will insert a chart in your report. Note that a separate license of RChart is required if you want to create charts. RReport includes a evaluation version of RChart.

This object only requires 1 parameter, the "Data File" that contains the chart parameters. This file is created using RChart Visual Builder.

 

RVUserComponent

This object is used to include a JComponent in your reports. When you insert a RVUserComponent in your report, a JLabel is displayed. In order to display your own JComponent (for example JEditorPane) you must set the rusercomponent.setruntimeValue(), for example:

JTextField component=new JTextField("Test"); // create own JComponent
// set JComponent in RUserComponent
((RUserComponent) report.getAreaByName("areaname").getItemByName("RUserComponent1")).setruntimeValue(component);

Note that the component must fit in one page (ie, you can print a large component like JEditorPane but you must make sure it will not exceeds the limit of the current page).

Evaluation of expressions

RReport can also evaluate expressions you enter in the "value" property of the RVField objects. Any value starting with "=" is assumed to be an expression to be evaluated unless you set the "evaluate" property of the RVField to "No".

Examples of expressions are:

Supported operators are: + , - , / , \ (integer division), ^ (power), *, % (modulo) and & (concatenation of strings).

Supported functions are:

Supported functions for group footers are:

You can implement your own functions using the IUserFunctions interface and setting the Evaluator.userFunctions property. For example, the following code would implement the "charAt" function that extracts a given character froma string.

 

class myFunctions implement IUserFunctions {

public Object executeFunction(String functionName,Object[] parameters) {

// implement charAt function which have 2 parameters: String and possition of the char to return
if (functionName.compareTo("charAt")==0)
if (parameters.length==2) {

String s=parameters[0].toString();
String positionStr=parameters[1].toString();
int position=Integer.parseInt(positionStr);

if (s.length()>position) return ""+s[position];
}

return new String("");

}

}

Note that user defined functions are only executed within your Java application. When testing the report inside RReport Visual Builder, user defined functions will be ignored.

 

Using a database

In order to retrieve data from a database you must:

  1. Enter the connection data in the Report's Properties
    1. Database URL: if you use a ODBC connection just enter the DSN here (see your ODBC administrator). If you use a JDBC[TM] native driver you should read the documentation on the driver to know the format of the url.
    2. Database user. If needed.
    3. Database password.If needed.
    4. Activate the database connection. Select YES in the DB Active combo box.
  2. Enter the table name or the SQL query in the Area's Properties (see DB Sel Table property). Each area will retrieve data from a table in the database. You can also have nested areas. In this case you must select a "linked Area" (super area) and enter the "link from" (fields in the supertable) and "link to" (fields on the subtable) information in the nested area (subarea). The "link from" and "link to" are list of fields separated by "|" that build the foreign key relationship between tables/areas.
  3. Enter the field name in the Object's properties. The following object support database access: RField, RCheck and RCombo.

 

Running the report

 

The following code will run the report DBorder.rep:

import java.awt.*;
import com.java4less.rreport.*;
public class exampleDBOrder extends Frame implements RAreaListener {
int total=0;
public static void main(String[] args) {
exampleDBOrder f=new exampleDBOrder();
f.setVisible(true);
f.init();
}

public void init()
{ // load report from file, this will also open the database connection to the ODBC Datase Source RReport
RReportImp report=new RReportImp(this);

// if you use JDK 1.2 or later you can use the Java 2 printing api:
// RReportJ2 report=new RReportJ2(this);


if (!report.importReport("DBorder.rep")) System.exit(0);

// set the images for the combo box. This can only be done programatically
java.awt.Image[] comboImages=new Image[3];
comboImages[0]=new RImageFile("ball1.gif").getImage();
comboImages[1]=new RImageFile("ball2.gif").getImage();
comboImages[2]=new RImageFile("ball3.gif").getImage();
((RCombo) report.getAreaByName("Detail").getItemByName("Priority")).Values=comboImages;

// set listener to calculate amounts on the fly
report.getAreaByName("Detail").setListener(this);
report.getReportFooter().setListener(this);

// create preview window
RReportWindow Win= new RReportWindow(report,this);

// you can also use the SWING preview window
//RReportJWindow Win= new RReportJWindow(report,this);

// this will print the Header Area and all dependent areas
report.prepare();
report.endReport();
Win.show();
System.exit(0);
}

// Area Listener. This will be triggered for each repetition of detail and page footer
public void beforePrintingArea(RArea area) {
// calculate the amount of each line
if (area.getName().compareTo("Detail")==0) {
double price=((Double) area.getItemByName("Price").getruntimeValue()).doubleValue();
int quantity=((Integer) area.getItemByName("Quantity").getruntimeValue()).intValue();
total=(int) (total+(quantity*price));
area.getItemByName("Amount").setruntimeValue(new Integer((int) (quantity*price)));
}

// set total amount
if (area.getName().compareTo("Footer")==0) {
area.getItemByName("Total").setruntimeValue(new Integer(total)); total=0;
}
}
}

 

The process is:

  1. The report is created by calling the constructor new ReportImp(frame). Note that you must use the class RReportImp or RReportJ2.
  2. load the report using importReport(file). This will also open the database (this example uses a ODBC data source called RReport that opens the database RReport2.mdb). Here you will find other examples that do not use database.
  3. Assigns the images for the combo box .
  4. sets the area listeners. This will be triggered for each repetition of detail and page footer.
  5. create a preview window if you need it.
  6. call prepare(). This will print the report header. The detail area will also be printed since it is a subarea of report header.
  7. call endReport().

 

Accesing loaded fields and methods:

In order to change the properties of object or area after loading a report from a file you must use the methods:

rreport.getAreaByName() and rarea.geItemByName().

for example. In order to change the image of a RPicture object you must call:

report.getAreaByName("areaname").getItemByName("RPicturename").setruntimeValue(Image)

note that if your want to access the headers, background or footers area you must use the rreport.getPageHeader(), rreport.getReportHeadert()...

Using your own database connection and statement for database access:

If your report uses a database, it will open the database connection when you execute the importReport() method. If you already have a database connection you can use your own java.sql.connection object in this way:

report.setDBCon(yourConnection);
report.importReport("filename");

The importReport() method will also create all necesary RAreas and RJDBSource objects. The RJBCSource's constructor needs a java.sql.Statement object as parameter. This will be created by report.getDBCon().createStatement().

If you want to specfiy your own Statement you must call:

((RJDBCSource) report.getAreaByName(name).getDataSource()).setStatement(yourStatement);

This may be necessary if you use some SQL Server drivers that need a new database connection for each statement. Note that RReport creates all statement from the same java.sql.Connection.

If you want to change the sql statement at runtime:

((RJDBCSource) report.getAreaByName(name).getDataSource()).setSQL("Select * from Employees");

 

Programatically printing

If you do not use any RSource you must print the imported report programatically ba setting the values of the ovject in the area one by one and printing every single repetition with rreport.printArea(). Like this:

report.importReport(name);
myArea=report.getAreaByName(areaname);

while (data to print) {
// set values for fields
myArea.getItemByName(fieldname1).setruntimeValue(value1);
myArea.getItemByName(fieldname2).setruntimeValue(value2);
.....

// print repetition
report.printArea(myArea);
}

See also exampleOrder2.java.

 

Using other RSources

In other to use other RSources (for example, printing a JTable) ,different from a JDBC[TM] driver, you must import the report and set the new RSource:

report.importReport(name);
report.getAreaByName(areaname).setDataSource(yourRSource);

See also exampleOrder.java for an example with a RArraySource.

 

Combining RSources and programatically printing

If you use a RSource object to print all repetitions of an area automatically but you still need to set a field value programatically your must use a RareaListener.

 

 

Creating your own RVObjects

 

Once you have created your own RObject, you can create a RVObject for it. RObject are the printable object while RVObject are the visual objects you see in RReport Visual Builder.

The steps to create your own RVObject are:

  1. create your own class extending RVObject . For example, if we take the RTriangle object from RReport user manual we would now create a class called RVTriangle.
  2. the new class must be located in the package com.java4less.rreportVB. In our example com.java4less.rreportVB.RTriangle.
  3. in order for RReport Visual Builder to load the new class you must create a text file called RVTriangle.txt and put it in the Objects subdirectory. This .txt file must contain a short (2-3 words) text that will be used as tip in the toolbar.
  4. in order to assign an icon for the object in the toolbar of RReport Visual Builder you must have a 16x16 pixels gif file called RVTriangle.gif and this image file must be located in the package com.java4less.images.

Click here (RVTriangle.java) to see the necesary code to create the RVTriangle class.

After examining the source code you will note that:

 

Examples

The following examples are delivered with RReport Visual Builder:

You can import the the *.rep files in RReport Visual Designer with File->load menu.

In order to run the examples the following files a provided:

 

Java, JSP, JDBC, JDK and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. J4L Components is independent of Sun Microsystems, Inc.