BackPrevious Page Next PageNext

JReport Catalog Bean

Installing the Catalog Bean

Catalog Bean classes

Preparations before using the Catalog Bean

Using the Catalog Bean

Creating a catalog

Loading an existing catalog

Manipulating a catalog

Getting information

Saving a catalog

Changing the catalog connection

Handling exceptions

Test tool program

JReport Catalog Bean provides a programming API for manipulating and accessing a JReport catalog. It enables you to create an empty catalog, add objects to a catalog, remove objects from a catalog, get an object description in a catalog and so on.

Installing the Catalog Bean

The Catalog Bean is available when you install JReport Designer. The following are the main components under the installation root that are required for using the Catalog Bean:

Catalog Bean classes

JReport Catalog Bean contains several classes: JRCatalog class, JRCatalogException class and ConnectionDesc class.

JRCatalog class

The JReport Catalog is the principal class that manipulates and accesses a catalog. The application creates a JReport Catalog instance, and uses JReport Catalog methods to manipulate the catalog.

JReport Catalog has two properties:

JRCatalogException class

JRCatalogException is the class that describes the error information. This exception is thrown when an error occurs. This exception describes many kinds of errors. The error code in the exception represents the exception type. The error code and error message can be viewed through public means.

ConnectionDesc class

ConnectionDesc is the class that describes the JDBC connection information. This class is used to create/modify connections and get connection information.

Reference: JReport Javadoc jet.bean.JRCatalog, jet.bean.JRCatalogException and jet.universe.ConnectionDesc classes in <install_root>\help\api, which includes all the documents generated by Javadoc.

Preparations before using the Catalog Bean

Before you can use the Catalog Bean to perform tasks, you need to import the Catalog Bean classes by adding the following import statements to the beginning of your program. The first two import statements are added to import the Catalog Bean, and exception classes. The third is added to import the connection description class.

import jet.bean.JRCatalog;
import jet.bean.JRCatalogException;
import jet.universe.ConnectionDesc;

Then you need to create an instance of the Catalog Bean. The constructor of the Catalog Bean has no parameter. After the object has been created, you should then set the report home to the object.

JRCatalog jrCatalog = new JRCatalog();
jrCatalog.setReportHome("c:\\jreport") ;

With the Catalog Bean object, you can manipulate and access many catalogs. You do not need to create a bean for each catalog.

Using the Catalog Bean

The Catalog Bean provides many useful methods. The following shows how to use the Catalog Bean to achieve some goals.

Note: After finishing working on a catalog, the closeCatalog method should be called to close the catalog. This will release resource and clear up the temporary file. Also, the program requires using the closeCatalog method when operations on it have been completed.

Creating a catalog

The method newCatalog creates an empty catalog according to the catalog name that is set in catName, and saves it to disk.

When creating a new catalog, the directory of the catalog name should exist and contain no catalog files. You should make sure of this before you start creating the new catalog.

Try
{ 
    jrCatalog.setCatName("c:\\a.cat"); 
    newCatalog(); 
} 
catch(JRCatalogException e) 
{
    System.out.println(e);
}

Loading an existing catalog

The method loadCatalog is used to load a catalog according to the catalog name that is set in catName.

try
{
    jrCatalog.setCatName("c:\\a.cat");
    loadCatalog();
} 
catch(JRCatalogException e) 
{ 
    System.out.println(e); 
}

Manipulating a catalog

A catalog can be manipulated by the actions of adding, deleting and editing of objects within it. A catalog contains many kinds of objects. These objects include connections, tables, views, synonyms, file queries, stored procedures, queries, WHERE portions, formulas, summaries and parameters.

For example, you can modify the connection, the name, the URL, the user, the password and the driver.

try 
{ 
    ConnectionDesc conDesc=new ConnectionDesc(); 
    conDesc.strName="Demo"; 
    conDesc.strURL="jdbc:oracle:thin:@myhost:1521:orcl"; 
    conDesc.strUser="system"; 
    conDesc.strPassword="manager"; 
    conDesc.strDriver="oracle.jdbc.driver.OracleDriver"; 
    jrCatalog.modifyConnection(conDesc);
} 
catch(JRCatalogException e)
{ 
  System.out.println(e);
}

Getting information

You can get information about objects in a catalog via some methods.

For example, you can get the connection information via the method getConnectionDesc().

Try 
{ 
    ConnectionDesc conDesc = bean.getConnectionDesc();
} 
catch(JRCatalogException e) 
{ 
    System.out.println(e); 
}

Saving a catalog

Changes to a catalog are saved to a disk only when the method saveCatalog is used.

Try 
{ 
    jrCatalog.saveCatalog(); 
}
catch(JRCatalogException e)
{ 
    System.out.println(e); 
}

Changing the catalog connection

In the following program, the Catalog Bean will be used to change the connection of a catalog:

try
{ 
// create catalog bean 
JRCatalog jrCatalog = new JRCatalog();
// set report home 
jrCatalog.setReportHome( "c:\\jrcbean"); 
// load catalog 
jrCatalog.setCatName("c:\\a.cat">);
loadCatalog(); 
// modify connection 
ConnectionDesc conDesc = new ConnectionDesc(); 
conDesc.strName = "Demo"; 
conDesc.strURL = "jdbc:oracle:thin:@myhost:1521:orcl"; 
conDesc.strUser = "System"; 
conDesc.strPassword = "Manager"; 
conDesc.strDriver = "oracle.jdbc.driver.OracleDriver"; 
jrCatalog.modifyConnection(conDesc);
// save catalog 
jrCatalog.saveCatalog(); 
// close catalog 
jrCatalog.closeCatalog(); 
}
catch(JRCatalogException e)
{ 
System.out.println(e); 
}

Handling exceptions

When an error occurs, the JRCatalogException is thrown out. Your program will catch the exception and handle the error.

The exception describes the error code and detailed message as follows:

Test tool program

TestCatalogBean.java located in <install_root>\help\samples\APICatalog, is a test tool for JReport Catalog Bean. It is primarily designed and built for you to test all the methods of JReport Catalog Bean.

The test tool program has a user interface, and all the functions of the Catalog Bean can be invoked using the menu items. Depending on success or failure of each test, you will get either a return result or an exception message respectively.

To run the JReport Catalog Bean test tool program, you should:

  1. Compile the source code of TestCatalogBean.java. For example, JReport Designer is installed in C:\JReport\Designer, you can compile the it using the following command (make sure that the path of the file JREngine.jar is before that of the file report.jar):

    C:\JReport\Designer\help\samples\APICatalog>javac -classpath "C:\JReport\Designer\lib\JREngine.jar;C:\JReport\Designer\lib\sac-1.3.jar;C:\JReport\Designer\lib\report.jar;" TestCatalogBean.java

  2. Run the test tool:

    C:\JReport\Designer\help\samples\APICatalog>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\hsqldb-2.4.0.jar" TestCatalogBean

    After activating the program, a window will be displayed.

  3. Before starting other commands, you should first set the home path and the catalog name.

    Select File > Set Home Directory to set the home path and File > Set Catalog Name to set the catalog name.

  4. Then, you can create a new catalog with the specified catalog name, or load an existing catalog in the same way.
  5. The test tool also provides the source code of each method, and you can copy and paste it into your program from the text window.

BackPrevious Page Next PageNext