Index

Server Data Management

Server Data Overview

While JReport Enterprise Server is running, it keeps track of server information and stores it to its own database for the purpose of running various management and monitoring tasks, such as managing resources on the server, monitoring the running task status, and collecting server running statistics.

The JReport Server data, which includes system tables and profiling tables, is saved in its own databases individually.

The JReport System database holds information on folders, nodes, versions, the security system, and the completed status table. The profiling database holds the server runtime performance related information.

Referrences: systables.sql, profiling.sql

JReport Enterprise Server provides approaches to manage the server data on a stand-alone server or in an integration environment by yourself. In this chapter about Server Data Management, you can achieve the following goals:

• Configure the Server database in a stand-alone environment
  • Checking and Warning about System Resource Problems at Startup
  • Configuring the Server database
  • Backing up/restoring Server data
  • Archive Server data and restoring archived data
  • Backup/archive of summary information
  • Clearing unused nodes in the System database
• Configuring the Server database in an integration environment
  • Configuring the Server database for JDBC
  • Configuring the Server database for JNDI

Configuring the Server Database in a Stand-alone Environment

In a stand-alone environment, all of the following features can be performed on the Administration page (8889) of JReport Enterprise Server to manage your server database.

Checking and Warning  about System Resource Problems at Startup

Relationships between the Server Database, Resource Tree, and Physical Folder

The Server database contains all the resources and information used by JReport Enterprise Server, such as catalog and report information, users, and schedules. The server resource tree gets resource information from the server database and structures them on the tree. Only the resources that are organized in the resource tree can be accessed and queried by the client. Each node of the resource tree has a physical folder in the disk, by default, all the physical folders are contained in <install_root>/history. You can also specify a real path for each resource node by checking the Enable Real Path option.

In abnormal circumstances, the server data may not be saved correctly or completely in the databases. JReport Enterprise Server allows you to check the integrality of the server data.

Keeping the consistency between resource node and physical folder

To keep the consistency of the server resource database and physical folder, JReport Enterprise Server will do the cleanup work at startup. The cleanup will be done differently for two cases:

• for the resource nodes which are not mapped to any external physical folders.
• for the resource nodes that are mapped to external physical folders.

No External Physical Folders are Specified

For the resources that are not be mapped to external physical folders, they will be mapped to <install_root>/history and managed by JReport Enterprise Server. Therefore, once you specify to do a cleanup, it will be done automatically without any prompt information.

Have External Physical Folders Specified

If you have mapped your resources to external physical folders, once you specify to do cleanup, JReport Enterprise Server will check the resource nodes against the mapped location, and prompt you if the physical folders do not exist. The warning information will be recorded in error.log in the <install_root>/logs folder.

Specifying to do the Cleanup

Two ways are provided for you to request that JReport Enterprise Server to do the cleanup:

• Add the JVM option -Dcheck.systables=true to the start command of JReport Enterprise Server or the JVM settings for the Java Application Server when using an embedded Server.
• In Java code using the Server API, add it to the Properties.
  
  Using the following demo code:
  
  System.getProperties().put("check.systables","true"); //Enable Cleanup
  System.getProperties().put("logall","true");
Properties prop = new Properties();
prop.setProperty("server.enableDynamicResource","true"); //Set
  server.enableDynamicResource to true
  HttpUtil.initEnv(prop);
this.rptServer = HttpUtil.getHttpRptServer();

System.out.println(" ========httpRptServer= " + this.rptServer + " starts up!");
  
  Notes:
  • You must set the property server.enableDynamicResource to true before the initEnv() method in order to enable the mapping folder.
  • The warning information will be saved in error.log, and you need to also specify the JVM property for a higher level of JReport Enterprise Server logging in order to see the error (–Dlogall=true).

Configuring Server Database

JReport Enterprise Server now provides multiple database support, allowing you to configure your own database to store server data, other than the default database that JReport Server uses by default which is Hypersonic (HSQLDB). The following are the two ways to configure your server database: 1) on the admin pages (8889) and 2) in the dbconfig.xml file. This file is automatically created when you install JReport Server. This file is used to store the configuration information of the database used in JReport Server. The two ways are equivalent, so you just need to choose either one of them. 

• Configure the server database on the Administration page of JReport Enterprise Server (8889):

1. On the top banner of the page, select the Data link.
2. Select the realm from the dropdown list.
3. Click the System DB or the Profiling DB tab. You can configure databases for System and Profiling individually.
4. Switch to the Configuration tab.
5. Select a DBDriver from the Driver drop down list or type the DBDriver here, and provide the driver class path information in the Driver Class Location field if necessary.
   
   Note: If you select a DBDriver named sun.jdbc.odbc.JdbcOdbcDriver in the Driver drop down list, we can not guarantee that the server can properly access the DBMS driven by it.
6. Type a valid URL that can be used to establish a connection to the database. A valid format of the URL should be provided by the DBDriver vender.
7. Provide user ID and password.
8. To test the connection, click Test. To update the database configuration to apply the settings, click Update and then restart the server to finalize this change.

• Configure the server database in the dbconfig.xml file under the <install_root>\bin directory. Here we provide some examples for your reference.
  
  The following example is for Oracle. Please modify the dbconfig.xml file as follows:
  
  

  <?xml version="1.0" encoding="UTF-8"?> <dbconfig> <workspace name="defaultRealm"> <database> <database name="systables"> <user>test</user> <url>jdbc:oracle:thin:@192.168.126.35:1521:ora9i</url> <password>1234</password> <driver classpath="D:\DBDriver\Oracle\oracle9i\ojdbc14.jar"> oracle.jdbc.driver.OracleDriver </driver> </database> </workspace> </dbconfig>

  
  The following example is for DataDirect driver. Please modify the dbconfig.xml file as follows:
  
  

  <?xml version="1.0" encoding="UTF-8"?> <dbconfig> <workspace name="defaultRealm"> <database name="systables"> <user>test</user> <url>jdbc:datadirect:sqlserver://192.168.126.35:1433;DatabaseName=sysdb</url> <password>1234</password> <driver classpath="D:\DBDriver\connectjdbc\lib\base.jar; D:\DBDriver\connectjdbc\lib\util.jar; D:\DBDriver\connectjdbc\lib\sqlserver.jar"> com.ddtek.jdbc.sqlserver.SQLServerDriver </driver> <dbtype>Microsoft SQLServer</dbtype> </database> </workspace> </dbconfig>

  
  Reference: For more about the DataDirect driver, please refer to the DataDirect documentation. The following are the drivers for different Databases supported by the DataDirect driver:
  
  com.ddtek.jdbc.db2.DB2Driver
com.ddtek.jdbc.informix.InformixDriver
com.ddtek.jdbc.oracle.OracleDriver
com.ddtek.jdbc.sqlserver.SQLServerDriver
com.ddtek.jdbc.sybase.SybaseDriver

  The following example is for DB2 database. Please modify the dbconfig.xml file as follows:
  

  <?xml version="1.0" encoding="UTF-8"?> <dbconfig> <workspace name="defaultRealm"> </database> <database name="systables"> <user>test</user> <url>jdbc:db2://dbs-b/sample</url> <password>1234</password> <driver classpath="D:\DBDriver\DB2\v81\db2java.zip;D:\DBDriver\DB2\v81\db2jcc.jar;"> COM.ibm.db2.jdbc.net.DB2Driver</driver> <tablespace>tablespace1</tablespace> </database> </workspace> </dbconfig>

  In the configuration information above, the tablespace1 in the tags <tablespace></tablespace> is the name of the table space, which is defined in the DB2 database. The table space is also supported for the Oracle database.
  
  JReport Enterprise Server supports data source JNDI name and resource reference name in dbconfig.xml. Use the <datasource></datasource> tags to specify the DataSource JNDI name or resource reference name.
  

  <?xml version="1.0" encoding="UTF-8"?> <dbconfig> <workspace name="defaultRealm"> <database name="systables"> <datasource>jndi://datasource-name</datasource> </database> </workspace> </dbconfig>

Notes:

• After the database is successfully connected, the username and password in the dbconfig.xml file will be encrypted. So the nodes 
  
  <user>test</user>
<password>1234</password>
  
  may become something like nodes shown below:
  
  <encrypt-sign>inG0qyMr89c2sIUwwDXN3dycTmeuQW5i</encrypt-sign>
• Storing the systables and the profiling data into two separate databases is strongly recommended.
• For the Access and HSQLDB Server, you don't need to specify the Driver Class Location; while for the other databases, you must provide the driver class path information unless it has already been added to the classpath of the JREntServer.bat file.
• When you configure the database URL in a clustered environment, please make sure that the setting for both admin and backup server points to the same database location, so that when the backup server is used instead of the admin server, the server data will be consistent.
• Normally, JReport Enterprise Server automatically creates system tables and profile tables the first time it starts. The database information that JReport Enterprise Server uses is defined in the dbconfig.xml file. However, if the user ID defined in that file doesn't have permission for creating tables in the database, JReport Enterprise Server will fail to complete the operations. In this case, you can have another user, such as the database administrator, who holds the relevant permissions, to create a set of empty tables in that user's schema using the SQL files provided, systables.sql and profiling.sql.

Backing up/Restoring Server Data

Backup server data

The server data backup process traverses all tables in the database, collecting data and exporting all table data to a ZipEntry. For certain tables, such as the catalog version table, report version table, and result version table, the data also includes relational real files in the history directory. All server data is compressed to a single Zip file. Every table's data and every relational real file are stored as a ZipEntry in this single file. Use BackUp and Restore to save the entire database and restore the entire database. It does not affect the size of the database.

You have two alternatives to export the server data:

• Through the JReport Server browser user interface.
• Through the command line.

To export the server data through the Server user interface,

1. On the top banner of the Administration page of JReport Enterprise Server, select the Data link.
2. Select a realm from the dropdown list.
3. Click the System DB  or Profiling DB tab.
4. Type the file path and name in the Backup System DB or Profiling DB in the archive field, or use the Browse button to specify the file path, and then click Backup. Please note that the file extension should be included.

To export the server data through the command line no Unix or Windows,

1. In the command line window, switch to the <install_root>\bin folder.
2. Use the DBMaintain command (DBMaintain.sh on Unix) and -Bsystables/-Bprofiling parameter, for example:
   
   C:\JREntServer\bin>DBMaintain -Bsystables:C:\TEMP\cmd_b_systables.zip -Bprofiling:C:\TEMP\cmd_b_profiling.zip

Restore server data

The server data restore process picks up every table’s data from the backup file and inserts it into the corresponding table in the database. You can only restore the server data using the DBMaintain tool with the -Rsystables/-Rprofiling parameter.

To import the server data using the command line,

1. In the command line window, switch to the <install_root>\bin folder.
2. Use the DBMaintain command and -Rsystables/-Rprofiling parameter, for example:
   
   C:\JREntServer\bin>DBMaintain -Rsystables:C:\TEMP\cmd_b_systables.zip -Rprofiling:C:\TEMP\cmd_b_profiling.zip

Backup/restore limitations

The backup/restore feature doesn't support cross-platform operation. The backup and restore operations must be done on the same operating system. For example, if you backup the server data to a zip file on a Windows platform, you will not be able to restore it on a Unix system. Since it is binary data, there will also be problems switching between different types of Unix systems such as Solaris and Linux.

Archiving and Restoring Server Data

Archiving Server Data

While running JReport server, the sizes of the result version table (DB: systables) and TaskContext table (DB: profiling) grow larger. JReport Enterprise Server allows you to archive and delete data to a single backup file. You can then retrieve the data from the backup file at a later date. Unlike Backup, when you Archive data the data is removed from the database and when you restore data from the archive it just adds the archived data back into the database and does not replace any existing data.

To archive the server data:

1. On the top banner of the Administration page of JReport Enterprise Server, click Data.
2. Select the realm from the dropdown list.
3. Click the System DB or Profiling DB tab.
4. Switch to the Archive tab.
5. Specify a time in the Move to archive data before field, and then type or use the Browse button to specify the file path and name in the To archive field.
   
   If you don't want to backup the archive server data, leave this field blank. The server data will then be removed from the database without saving it to an archive file.
6. Click Archive. Server data prior to the time specified will be removed from the database and saved to the archive file using the name specified.

Restoring the Archive Server Data

You can restore server data that has been archived from an archive file. You can only restore it using the server user interface.

To restore the archived server data:

1. On the top banner of the Administration page of JReport Enterprise Server, click Data.
2. Select the realm from the dropdown list.
3. Click the System DB or Profiling DB tab.
4. Switch to the Archive tab.
5. Type or use the Browse button to provide the archive file name and location in the Restore from archive field, and then click Restore.

Archive/Cutdown Summary information

After archiving or backing up files, you can view the archive or backup summary information from the summary tab, which includes Archive, Date, Type, Version, Realm, Database and Scope.

To view the summary information of a specified file,

1. On the top banner of the Administration page of JReport Enterprise Server, click Data.
2. Select the realm from the dropdown list.
3. Select the System DB or Profiling DB tab.
4. Switch to the Summary tab.
5. Type or use the Browse button to specify an archive or backup file name and location in the Archive field, and then click Summary.

System DB Check of the System Database

Making operations on dynamic resources may generate garbage unused nodes in the System Database. The unused nodes can be cleared through the Administration page.

How unused dynamic nodes are generated

If you do not use the real path option it is unlikely you will need to check the database. If you are using a real path for a folder to get a dynamic resource, and then use advanced run for a report in this folder and archive its version or successfully publish the report to the version system, it is possible to generate unused nodes. if you do either of the following operations, the unused dynamic nodes will be generated in the System Database:

• Cancel or change the real path setting.
• Deploy a resource to replace an existing dynamic resource.

How to clear invalid dynamic nodes

To clear unused nodes on the Administration page, perform the following steps:

1. On the top banner of the Administration page of JReport Enterprise Server, click Data.
2. Select the System DB or Profiling DB tab.
3. Select the System DB Check tab.
4. Select the Check button.
5. If any Invalid Nodes are listed, check the check-box on the header of the first column to specify whether you want to select all or unselect all. Otherwise, you can check the corresponding check-box to select the invalid dynamic nodes that you want to delete.
6. Selecting the Delete button will delete all selected nodes.
7. Select the Cancel button to return to the previous page.

Configuring Server Database in an Integration Environment

Here we illustrate two potential environments to configure the server database in an application server environment: first in a JDBC environment and second in a JNDI environment. You can go through the following sections to get help. These are just two of many possible ways you can integrate JReport Server into your application environment.

Configuring Server Database for JDBC

In the JDBC environment, JReport Enterprise Server provides multiple database support, which allows you to configure your own database, rather than just using the default database that JReport Server uses. Before you integrate JReport Server with other application servers, you can generate a web.xml file to specify a different database to use. Here we give you two cases for your reference.

After you generate a web.xml file, the priority to look for the database connection information is like this: web.xml followed by dbconfig.xml. However, if you do not specify the web.xml files, the dbconfig.xml, which uses the default database - HSQLDB, will be applied.

Case I: Integrating JReport Enterprise Server with JBoss 4.0

Before integrating JReport Enterprise Server with JBoss 4.0, if you want to configure your own database rather than using the default database, you can first create a web.xml file as follows:

Here we take the IBM DB2 database db2 as an example:

<web-app> <env-entry> <env-entry-name>jreport.datasource.systables</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>jdbc://user:password@jdbc:datadirect: db2://dbs-b/tempdb#driver=COM.ibm.db2.jdbc.net.DB2Driver </env-entry-value> </env-entry> ... </web-app>

Reference: For more information about how to integrate JReport Enterprise Server with JBoss 4.0, please refer to Integrating JReport Enterprise Server with a Java Application Server.

Note: Under the condition of integrating JReport Enterprise Server with JBoss, if you have modified a web.xml file as the above example to configure your database as DB2, you should also copy db2java.zip and db2jcc.jar into the servlet\WEB-INF\lib directory.

Case II: Integrating JReport Enterprise Server with WebSphere 5.1

Before integrating JReport Enterprise Server with WebSphere 5.1, if you want to configure your own database rather than using the default database, you can first modify a web.xml file as follows.

Here we take the Oracle database as an example:

<web-app> <env-entry> <env-entry-name>jreport.datasource.systables</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>jdbc://test:1234@jdbc:oracle:thin:@OracleHost:1521 :orc1#driver=oracle.jdbc.driver.OracleDriver,classpath =D:\DBDriver\Oracle\oracle9i\ojdbc14.zip </env-entry-value> </env-entry> ... </web-app>

Reference: For more information about how to integrate JReport Enterprise Server with WebSphere 5.1, please refer to Integrating JReport Enterprise Server with a Java Application Server.

Configuring Server Database for JNDI

When JReport Server runs, it will save or retrieve data such as Scheduled Tasks, Complete Tasks, Report/Catalog Versions, and User/Role information. By default, such information is saved in the built-in DB--HSQLDB. JReport Server calls the HSQLDB driver to connect with the database. However, you can specify to save or retrieve the data from different databases or data sources.

As you know JReport Server supports connecting to a RDBMS to access its system data via JDBC. The JDBC configuration information is stored in server\bin\dbconfig.xml -- create database connection according to the configuration file. With the J2EE data source support feature, JReport Server can get the predefined javax.sql.DataSource by JNDI APIs in a J2EE environment.

You can specify a parameter in the web.xml, so that JReport Server uses a predefined data source to interact with the RDBMS in a J2EE environment. This parameter also can be provided directly to the Java VM using the "-D" parameter or through JReport Server's API.

This feature only works in a J2EE embedded environment, that is, JReport Server is running in a WAR/EAR package which is deployed to an application server such as JBoss, WebSphere, WebLogic or Tomcat, etc.

This document also assumes that you have created the JNDI data source in your J2EE environment.

We will use the term dsInfo to indicate what JReport Server gets from JDBC connection. It is a key-value pair that should be passed to JReport Server through JVM properties.

The name and value for dsInfo is defined as follows:

The name should be: jreport.datasource.<dbname>. The <dbname> here is JReport Server's inner db name. It must be "systable" or "profiling". For example, the dsInfo name could be:

jreport.datasource.systables

The value should be a URL form; the following protocol is supported by JReport Server:

• jndi://[<jdbc-user:jdbc-passoword>@]datasource_name[#<attribute-name=attribute-value>,]
  
  For example: jndi://jdbc/jreport-systables

For the DB2 database, which has defined table spaces: jndi://jdbc/jreport-systables#tablespace=tablespace1

JNDI in Embedded J2EE Environment (.war)--WEB-INF/web.xml

In this mode, the JReport Server works as a WAR package in a J2EE environment.

If we want to let JReport Server use a predefined JNDI DataSource, the dsInfo should be specified in the web application's context. That is, in the WEB-INF/web.xml file, we should add a <env-entry> element like following:

<web-app> <env-entry> <env-entry-name>jreport.datasource.systables</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>jndi://datasource_name_which_is_predefined</env-entry-value> </env-entry> ... </web-app>

Then, when the JReport Server's instance is created, it will get this context parameter from WEB-INF/web.xml and look for the specified datasource to interact with the specified RDBMS.

Case I: Registering JNDI in JBoss 4.0.1

1. Create a mssql-ds.xml file as follows:
   
   

   <?xml version="1.0" encoding="UTF-8" ?> <datasources> <local-tx-datasource> <jndi-name>systables</jndi-name> <connection-url>jdbc:microsoft:sqlserver://servername:1433;DatabaseName=tempdb</connection-url> <driver-class>com.microsoft.jdbc.sqlserver.SQLServerDriver</driver-class> <user-name>sa</user-name> <password>password</password> </local-tx-datasource> </datasources>

2. In WEB-INF/web.xml file it should be defined as follows:
   

   <web-app> <env-entry> <env-entry-name>jreport.datasource.systables</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>jndi://jdbc/systables</env-entry-value> </env-entry> … </web-app>

3. Copy the mssql-ds.xml and servlet.war files into C:\jboss-4.0.1\server\default\deploy folder.

Case II: Registering JNDI in WebSphere 5.1

1. Open http://hostname:9090/admin (port may vary at your installation).
2. After successfully logging in, expand the Resources node, and then click JDBC Providers.
3. Click the New button.
4. Select a JDBC provider - Microsoft JDBC driver for MSSQL Server 2000, then click the OK button.
5. In the Name field, type in test. Specify the classpath, then click the OK button.
   
   
6. Select the test link.
   
   
7. Then select the Data Sources link.
8. Then click the New button to create a data source.
   
   
9. Specify the settings as below, then click OK.
   
   
10. Click the Systable data source link.
    
    
11. Select Custom Properties.
12. Specify the properties as shown below:
    
    
13. Click Save in the top area to apply changes to the master configuration.
14. In the popup dialog, click Save.
    
    
15. To test the connection, first visit the Data Sources page following the sequence: JDBC Providers - test - Data Sources.
    
    
16. Select the Systable data source by checking the checkbox, then click Test Connection.
17. Modify the web.xml file. JReport Enterprise Server supports to use resource reference name to look up the database information. If you want to use the resource reference name, in the the web.xml file, please modify the configuration like this:
    

    <web-app> <env-entry> <env-entry-name>jreport.datasource.systables</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>jndi://jdbc/jreport</env-entry-value> </env-entry> <resource-ref id="resDS"> <res-ref-name>jdbc/jreport</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref> … </web-app>

    Please bind the resource reference name with the data source JNDI name, using the tool WebSphere Studio Application Developer (recommended).

Important Notes

• The dsInfo can be specified in several places or levels, such as JVM properties, ejb-jar.xml, web.xml and JREntServer\bin\dbconfig.xml. The sequence to load the information is
  
  JVM -- HttpUtil.initEnv(props) -- CustomizedServerEnv -- ejb-jar.xml -- web.xml -- dbconfig.xml
• Please do not use reporthome, @ or # in JNDI name or Resource name.

Index