BackPrevious Page Next PageNext

JReport Design API

Design API packages & license

Installing the Design API

Preparations before using the Design API

Getting started using the Design API

Using the Design API

Creating, opening, closing and deleting a report

Inserting, moving and deleting an object in a report

Getting object property information

Getting report metadata information

Getting objects and object information

Getting editing information

Working with library components

Design API samples

Besides editing reports in the design area in JReport Designer, you can also edit them with the Design API. By creating a Designer instance in your Java program, you can design and modify a report with the methods provided by the Design API.

JReport Design API fully realizes designing a report programmatically. That is, with the Design API you can edit the layout of a report all in code. You can change the property values, or modify the report by inserting objects such as tables, crosstabs, chart, DBFields, formulas, labels, images and so on.

Design API packages & license

There are two JReport Design API packages: the workstation version and the server version. The workstation package is the Design API, and the server package is the Server Design API. The main difference between these two packages is that when invoking the special methods for editing catalogs, queries, reports, and parameters in the Server Design API, you also have to provide an additional parameter: UID (used to distinguish between different users, and can be a Number or a String). However when invoking them in the Design API, you do not need to provide this parameter.

JReport Design API and JReport Server Design API use an independent license from other JReport products. You need to contact Jinfonet sales to obtain this special license key if you want to use either JReport Design API or JReport Server Design API on your machine with JReport Designer or JReport Server. The license will be applied to your program instead of being applied to the installation of JReport Design API or JReport Server Design API.

The keys for JReport Design API and JReport Server Design API are different. For example, you cannot use the JReport Design API key on JReport Server Design API, and vice versa. Which key is required is based on where you set your class path at runtime. If the classes are obtained from <server_install_root>\lib you need to use the Server Design API key. If the classes are obtained from <designer_install_root>\lib you need to use the Design API key.

To use the key you need to create a DesignerUserInfo instance. Use the following constructor to provide the user ID and the Server Designer License Key or Designer License Key you received when you purchased JReport.

DesignerUserInfo userInfo=new DesignerUserInfo(Uid, key);
Designer desg = new Designer(catalogPath, catalogName, userInfo);

If you want to use JReport Design API or JReport Server Design API package for workstations without using JReport Designer and JReport Server, you will need to obtain a valid license for each work station.

Installing the Design API

The full Design API packages are included in JReport Designer and JReport Server. JReport Designer includes a single threaded Design API, while JReport Server includes a multi-threaded Design API. JReport Design API and JReport Server Design API packages can also be downloaded and installed to your local machine. After which, you can then program with them without having to install any other JReport products.

To install the Design API by JReport Designer:

When you install JReport Designer, the Design API is also installed at the same time. After installation, you will have the components listed below in <designer_install_root>\lib:

The Design API classes are stored in the archive files: report.jar and JREngine.jar. You will need to take the following two steps before you can compile and run the program:

  1. Set the classpath environment variable. Append the following string to your class path that starts the Design API (make sure that the path of the file JREngine.jar is before that of the file report.jar):

    <designer_install_root>\lib\JREngine.jar;<designer_install_root>\lib\report.jar;<designer_install_root>\lib\log4j-core-2.10.0.jar;<designer_install_root>\lib\log4j-api-2.10.0.jar;<designer_install_root>\lib\sac-1.3.jar;<designer_install_root>\commons-codec-1.11.jar;

  2. Add the jar files for your DBMS JDBC drivers.
  3. Set the -Dreporthome parameter to be the same as the root path of JReport Designer.
  4. You will need to register the Design API licensed user and license key in your source code.

To install the Design API by JReport Server:

When you install JReport Server, the Server Design API is also installed at the same time. After installation, you will have the components listed below in <server_install_root>\lib:

The Server Design API classes are stored in the archive files: JRESServlets.jar and JREngine.jar. You will need to take the following two steps before you can compile and run the program:

  1. Set the classpath environment variable. Append the following string to your class path that starts the Design API:

    <server_install_root>\lib\JRESServlets.jar;<server_install_root>\lib\JREngine.jar;<server_install_root>\lib\log4j-core-2.10.0.jar;<server_install_root>\lib\log4j-api-2.10.0.jar;<server_install_root>\lib\sac-1.3.jar;<server_install_root>\commons-codec-1.11.jar;

  2. Add the jar files for our DBMS JDBC drivers.
  3. Set the -Dreporthome parameter to be the same as the root path of JReport Server.
  4. You will need to register the Server Design API licensed user and license key in your source code.

To install independent JReport Design API:

Ask the Jinfonet Support (support@jinfonet.com) for the independent Design API installation file. Then, run the file and follow the prompts to install.

After you have installed JReport Design API by running the installation file, you will need to take the following two steps before you compile and run the program:

  1. Set the classpath environment variable. Then, append the following string to your class path that starts the Design API:

    <designAPI_install_root>\lib\designAPI.jar;<designAPI_install_root>\lib\log4j-core-2.10.0.jar;<designAPI_install_root>\lib\log4j-api-2.10.0.jar;<designAPI_install_root>\lib\sac-1.3.jar;<designAPI_install_root>\lib\commons-codec-1.11.jar;<designAPI_install_root>\lib\hsqldb-2.4.0.jar

  2. Set the -Dreporthome parameter equal to the root path of the Design API.

To install independent JReport Server Design API:

Ask the Jinfonet Support (support@jinfonet.com) for the independent Server Design API installation file. Then, run the file and follow the prompts to install. We don't recommend using these libraries, we recommend you use the Design API libraries included in JReport Server.

After you have installed JReport Server Design API by running the installation file, you will need to take the following two steps before you compile and run the program:

  1. Set the classpath environment variable. Then, append the following string to your class path that starts the Server Design API:

    <svrdesignAPI_install_root>\lib\serverDesignAPI.jar;<svrdesignAPI_install_root>\lib\log4j-core-2.10.0.jar;<svrdesignAPI_install_root>\lib\log4j-api-2.10.0.jar;<svrdesignAPI_install_root>\lib\sac-1.3.jar;<svrdesignAPI_install_root>\commons-codec-1.11.jar;<svrdesignAPI_install_root>\hsqldb-2.4.0.jar

  2. Set the -Dreporthome parameter to be the same as the root path of the Server Design API.

Preparations before using the Design API

Before you can use the Design API to perform certain tasks, you need to first make the following preparations.

Setting the license key

The license information is set via a method called setUserInfo(String uid, String key), where UID is the user ID, and key is the license key. This method should be called before you can call any other Design API methods. The UID is the license user ID you received with the purchase of JReport Server and JReport Designer. The license key will be either Server Designer License Key or Designer License Key depending on your class path setting to <server_install_root>\lib or <designer_install_root>\lib respectively.

DesignerUserInfo userInfo=new DesignerUserInfo(Uid, key);
Designer desg = new Designer(catalogPath, catalogName, userInfo); // For creating page report
MultipliedDesigner md = new MultipliedDesigner(path, catName, Designer.CAT, userInfo); // For creating web report

Getting a Catalog API instance

Before working with reports using the Design API, you need to specify the catalog in which they are saved. The method public CatalogAPI getCatalogAPI() is used for getting a Catalog API instance.

Getting handle information

All the objects in a report are organized into and browsed from a tree structure. For each report, the Report Inspector consists of a report objects tree at the top of the view panel and its corresponding reporting features or properties at the bottom. Selecting any object node on the tree also selects the same element in the report design area. The following diagrams cover all objects that can be used in a report with their relationships.

Report Set Diagram

Banded Object Diagram

Table Diagram

Crosstab Diagram

Every node and object in the above trees is identified by a HANDLE in JReport Design API. Therefore, before you can create or edit a report with the Design API, you will first have to get the handle information. Super class API provides the following methods to get handles of different nodes and different types.

Below are the parameters used in the methods:

Getting started using the Design API

To help you start using the Design API, here is a simple example which shows how to use the JReport Design API package to compile and run a Java class that returns the connection information from a catalog file.

  1. Compile the sample code TellMeConnection.java in <install_root>\help\samples\APICatalog (make sure that the path of the file JREngine.jar is before that of the file report.jar).

    javac -classpath <install_root>\lib\JREngine.jar;<install_root>\lib\sac-1.3.jar;<install_root>\lib\report.jar TellMeConnection.java

  2. Set the license key for Design API using the method dr.setUserInfo("UID","XXXXXXXXXXX") in TellMeConnection.java.
  3. Run the sample code.

    java -classpath ".;<install_root>\lib\JREngine.jar;<install_root>\lib\report.jar;<install_root>\lib\sac-1.3.jar;<install_root>\lib\log4j-core-2.10.0.jar;<install_root>\lib\log4j-api-2.10.0.jar" -Dreporthome=<install_root> TellMeConnection –path=<catalog path> -catalog=<catalog name>

    For example,

    java -classpath "C:\JReport\Designer\lib\JREngine.jar;C:\JReport\Designer\lib\report.jar;C:\JReport\Designer\lib\sac-1.3.jar;C:\JReport\Designer\lib\log4j-core-2.10.0.jar;C:\JReport\Designer\lib\log4j-api-2.10.0.jar;C:\JReport\Designer\lib\hsqldb-2.4.0.jar" -Dreporthome=C:\JReport\Designer TellMeConnection -path=C:\JReport\Designer\Demo\Reports\TutorialReports -catalog=JinfonetGourmetJava.cat

    And the output should be as follows:

    Name: Jinfonet demo
    Driver: org.hsqldb.jdbcDriver
    URL: jdbc:hsqldb:c:\JReport\Designer\Demo\db\JRDemo
    User: sa
    Password
    TimestampFormat: yyyy-MM-dd HH:mm:ss.SSS
    TimeFormat: HH:mm:ss
    DateFormat: yyyy-MM-dd
    ExtraNamePattern: Default(JDBC)

Using the Design API

The class API is the root of the class hierarchy of JReport Design API (Design API and Catalog API). It is an abstract class and provides a series of editing methods for users. The Design API class has an API as a super class.

Designer is the principal class that manipulates reports. The application creates a Designer instance and calls Designer methods to create or modify a report. For details of summary of FIELD, CONSTRUCTOR and METHOD, see JReport Javadoc jet.api package in <install_root>\help\api, which includes all documents generated by Javadoc.

Note that after finishing using the Design API, you need to call the following methods to exiting from the editing status.

Creating, opening, closing and deleting a report

When creating reports, the reports should be created based on an existing catalog file, otherwise you will get an error.

Parameters

Inserting, moving and deleting an object in a report

To insert an object in a report, you can use the methods below:

To change the position of an object, use the following method:

To delete an object from a report, use the following method:

Parameters

Getting object property information

The following methods are used for getting the property values of different types and return the property value:

Parameters

Note: The getControlFields(String handle, String name) method is used for getting fields that can control property values at runtime.

The following methods are used to get the property name, type and check property name:

Parameters

The following methods are used for changing the property values of different types. They will return true if the value is changed.

Parameters

Note: The setControlFields(String handle, String prop, String field) method is used for setting a field to control the property value at runtime. The setReference(String handle, String name, String refHandle) method is used for changing the reference property value of an object.

Getting report metadata information

Dataset information can be got by the method getDataSet(), which returns the dataset object. Then the following report metadata information can be got from the dataset: basic information, query information, business view information, data buffer information.

The following methods are used to get the basic information:

The following methods are used to get information of the query, imported SQL or other data objects that are used to create the dataset.

The following methods are used to get the business view information that is used to create the dataset.

The following methods are used to get the data buffer information:

Getting objects and object information

Parameters

Getting editing information

Working with library components

The entry API for working with library components is getLCEditor(). All the following operations use it as the entry.

Parameters

Design API samples

JReport provides you with some sample programs which demonstrate how to create and edit reports using the Design API in <insatll_root>\help\samples\APIDesign. They are:

To compile and run the sample programs, you should add jar files with their paths into the class path. Different jar files are required according to how the Design API is installed.

For example, you can use the following command to compile the sample program TestDesignInvoice.java:

C:\JReport\Designer\help\samples\APIDesign>javac -classpath "C:\JReport\Designer\lib\JREngine.jar;C:\JReport\Designer\lib\sac-1.3.jar;C:\JReport\Designer\lib\report.jar;C:\JReport\Designer\lib\log4j-core-2.10.0.jar;C:\JReport\Designer\lib\log4j-api-2.10.0.jar" TestDesignInvoice.java

When you run the sample programs, you need to provide two or three parameters. If you want to use two parameters, they should be catalog path and catalog name; if you want to use three parameters, they should be catalog path, catalog name and log file with a full path name.

The following example uses three parameters to run TestDesignInvoice.java. Here, it is assumed that JReport Designer has been installed to C:\JReport\Designer, and the current directory when you execute these commands is C:\JReport\Designer\help\samples\APIDesign (location of the sample programs). After running the program, you will find a newly created file TestInvoice.cls in C:\JReport\Designer\Demo\Reports\TutorialReports.

C:\JReport\Designer\help\samples\APIDesign>java -Dreporthome="C:\JReport\Designer" -classpath "C:\JReport\Designer\lib\JREngine.jar;C:\JReport\Designer\lib\sac-1.3.jar;C:\JReport\Designer\lib\report.jar;C:\JReport\Designer\lib\log4j-core-2.10.0.jar;C:\JReport\Designer\lib\log4j-api-2.10.0.jar;C:\JReport\Designer\lib\resource_en_US.jar;C:\JReport\Designer\lib\hsqldb-2.4.0.jar" TestDesignInvoice -path=C:\JReport\Designer\Demo\Reports\TutorialReports -catalog=JinfonetGourmetJava.cat -report=TestInvoice.cls -log=C:\JReport\Designer\logs\designer.log

BackPrevious Page Next PageNext