Using JReport Catalog Bean

1 Introduction

The JReport Catalog Bean provides a programming API to manipulate and access to the catalog of JReport.  The catalog is used to hold all the resources that are used to build a report in JReport.

The JReport Catalog Bean enables applications to:

The JReport Catalog Bean requires JDK1.1.6 or above version.

2 Installation   

JReport Engine is presently available for both Windows and Unix.

Installation For Windows NT and 95

In  Windows NT and 95, the setup program is an executive file called CatBeanSetup.exe. The setup program will guide you to install step by step, and install the files to your disk.  After The JReport Catalog Bean is installed, the following files are placed in your installed directory.

You need to set the CLASSPATH environment variable before you compile and run the program.  Append the following string to the CLASSPATH:

  <catalogbean_install_dir>\lib\JRCatalog.zip

Installation For Unix

In the Unix, the setup program is an executive file called CatBeanSetup.sh. The setup program will install the files to your disk.  After The JReport Catalog Bean is installed, the following files are placed in your installed directory.

You need to set the CLASSPATH environment variable before you compile and run the program.  Append the following string to the CLASSPATH:

<catalogbean_install_dir>/lib/JRCatalog.zip

3.1 Classes

JRCatalog Class

JRCatalog is the  principal class that manipulates and accesses to the catalog.  The application creates JRCatalog instance and calls JRCatalog methods to manipulate the catalog.

The JRCatalog has two properties:

reportHome

The string that contains the installation path of JReport Catalog Bean

catName
The string that contains the full file path of catalog.   The path will be used in loading or creating the catalog.

For further information, please refer to the JavaDoc documentation.

JRCatalogException Class

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

For further information, please refer to the JavaDoc documentation.

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

For further information, please refer to the JavaDoc documentation.

4. Programming with JReport Catalog Bean

4.1 Import

Import the JReport Catalog Bean classes by adding the following import statement at the beginning of your program.  The first two import statements bring into the bean class and exception class;And the third adds to  the connection description class.

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

4.2 Create an instance

To manipulate the catalog, you should create an instance of the Catalog Bean first.  The constructor of catalog bean has no parameter.   After the object is created, you should set the report home to the object. 

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

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

You can load an existing catalog or create a new catalog. After the catalog  is  created or loaded, you can manipulate the catalog before you close it. The closeCatalog method closes the catalog and releases resource and clears temporary file, and the program needs to call the closeCatalog method when the operation on the catalog is completed.

4.3 Create a new Catalog.

The newCatalog method will create an empty catalog according to the catalog name set in catName, and save the catalog to disk.

When creating a new catalog, the directory of the catalog name should exist, and contain no catalog file.  You shall make it sure before you create a new catalog.

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

4.4 Load an existing Catalog

The loadCatalog method will load the catalog according to the catalog name set in catName.

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

4.5 Manipulation

The manipulation is adding, deleting and editing the objects in the catalog.  Catalog contains many kinds of objects. The objects include connection, table, view, file query, stored procedure, query, where portion, formula, summary and parameter. Ideally, all the objects can be manipulated by program via the catalog bean, but in the initial version,only a few objects can be manipulated via the catalog bean.

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

4.6 Access

The access is getting information of objects in catalog.

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

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

4.7 Save

The changes on catalog will save to disk only when user calls the saveCatalog method.

For example,

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

4.8 Handle Exception

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

The exception describes the error code and detail message as following:

Code: 0
Message: "System initialize failed."
Description: The system initialize failed. The JRCatalog need to be initialized to resolve the environment. This error is caused by some reasons like wrong report home, bad installation.
Detail: The reason why initialize failed.

Code: 1
Message: "The catalog name is null."
Description: The catalog name is null. The catalog name should be set before the loadReport() or newReport() called.
Detail: None.

Code: 2
Message: "Create the catalog failed.Because the specified directory does not exist or there is an existing catalog in that directory."
Description: Cannot create a catalog in the specified directory, because the directory does not exist or there is catalog in the directory.
Detail: None

Code: 3
Message: "Cannot open the catalog file."
Description: Cannot open the specified catalog file. The reason is file not found, file corrupt, format error or version mismatch.
Detail: The reason why catalog file opens failed.

Code: 4
Message: "Save catalog failed."
Description: Cannot save the catalog file successfully. The reason is file write error or formula file save failed.
Detail: The reason.

Code: 5
Message: "No catalog loaded."
Description: The loadCatalog() or newCatalog() method should be called before other method is called. And the closeCatalog() should be called in the end.
Detail: None

Code: 6
Message: "The name of the where portion is invalid or already exists."
Description: The name specified is invalid or already used by other where portion.
Detail: None

Code: 7
Message: "The specified where portion does not exist."
Description: The specified where portion does not exist.
Detail: None.

Code: 8
Message: "A catalog can contain only one connection."
Description: A catalog can contain only one connection, and this error occurrs when adding the second connection.
Detail: None.

Code: 9
Message: "The name of the connection is invalid or already exists."
Description: The name specified is invalid or already used.
Detail: None

Code: 10
Message: "Connection failure."
Description: The JDBC connection failed when trying to create a connection to database.
Detail: The message of SQLException or ClassNotFoundException.

Code: 11
Message: "The name of the file query (customer SQL) is invalid or already exists."
Description: The name of file query is either valid or exists.
Detail: None.

Code: 12
Message: "Cannot create the file query."
Description: Cannot create file query object.
Detail: The reason.

Code: 13.
Message: "There is no connection in the catalog."
Description: There is no connection in the catalog. If you are deleting or modifying
the connection, the problem is no connection exists at all. If you are
adding file query, the problem is you can not create file query without
a connection.
Detail: None

Code: 14.
Message: "The specified file query doesn't exist."
Description: The specified file query does not exist.
Detail: None.

Code: 15.
Message: "Unknown Error."
Description: The unexpected error.
Detail: None

4.9 Sample for Catalog Bean

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

5. Test program.

The test program is a test tool of JReport Catalog Bean.  It is primarily designed and built for user to test all methods of Catalog Bean.

The test program has a user interface; All the methods of Catalog Bean can be invoked by the menu item. You can get the return result, or the message of exception.

The test tool also provides the source code of each method call; you can copy them from the text window and put to your program.

Please refer the source code of the test program.