Description

This package adds support for using Oracle Berkeley DB (BDB) as a data source within JasperReports Library, iReport Designer and JasperReports Server. It supports both direct access to a BDB database via the base API and access via the Direct Persistence Layer (DPL) of Berkeley DB. It has been tested with JasperReports Library v3.0, iReport Designer v3.0, JasperReports Server v3.0 and Oracle Berkeley DB 4.7.25.

Installing in iReport Designer

Before you can create a report that uses Berkeley DB as a data source, you need to install the BDB plugin into iReport Designer. The plugin registers "bdb" as a query language and adds support for running a BDB query and automatically creating report fields from the returned data. At the time this document was written the NetBeans based version of iReport Designer was still in early Beta. All testing has been done with the Swing version, and some of the descriptions in this document will not directly match what you see in the NetBeans version. Installing the BDB plugin for iReport Designer is straight forward.

1. Copy the file lib/jasperreports-bdb-<version>.jar to iReport Designer's lib directory.

    

2. Copy the Berkeley DB jar db-<version>.jar to iReport Designer's lib directory.

3. Add the location of your compiled BDB libraries to the script that starts iReport Designer. Go to $IREPORT_HOME/bin and edit either startup.bat (Windows) or startup.sh (*nix, Mac OS X). Add -Djava.library.path= . As an alternative you can set the environment variable LD_LIBRARY_PATH (use DYLD_LIBRARY_PATH on Mac OS X) to point to your Berkeledy DB libraries, but you must have it set every time you launch iReport Designer.

   On my system I have the libraries in /usr/local/BerkeledyDB.4.7/lib, so the last line of startup.sh reads

   java -classpath "$IREPORT_CLASSPATH:$CLASSPATH"

   -Direport.home=$IREPORT_HOME

   -Djava.security.policy=$IREPORT_HOME/policy.all

   -Djava.library.path=/usr/local/BerkeleyDB.4.7/lib

   it.businesslogic.ireport.gui.MainFrame "$@"

   If your path to the compiled libraries has spaces in it you must enclose the path in double quotes. This is fairly common on Windows systems.

4. Copy your applications Entities into iReport Designer's lib directory.

    

5. Exit and restart iReport Designer for your changes to take effect

Installing in JasperReports Server

Before you can use Oracle Berkeley DB as a data source inside JasperReports Server you need to install the JasperReports Server plugin. The actual JasperReports Server plugin for Oracle Berkeley DB is in the main jar file. In addition there are two support files you need to install as well, to tell JasperReports Server how to access the plugin.

1. Copy the file lib/jasperreports-bdb-<version>.jar to WEB-INF/lib in the JasperReports Server web application home.

    

2. Copy your Oracle Berkeley DB jar db-<version>.jar to WEB-INF/lib in the JasperReports Server web application home.

    

3. Copy jasperserver/applicationContext-bdbDS.xml to WEB-INF in the JasperReports Server web application home.

    

4. Copy jasperserver/bdb.properties to WEB-INF/bundles in the JasperReports Server web application home.

    

5. Restart the application server that JasperReports Server is deployed in.

You need to make sure that the application server can find the compiled libraries use by Oracle Berkeley DB, as described in the section on setting the library path in Installing in iReport Designer. Many application servers have fairly complicated strtup files, so it is often safer to add a line to them setting LD_LIBRARY_PATH (use DYLD_LIBRARY_PATH on Mac OS X) instead of setting a property on the java command line.

Configuration

The Oracle Berkeley DB data source needs to be configured to be able to open and use your Berkeley DB database. You need to configure the data source everywhere you plan to use it, typically once for use by iReport Designer and once for use by your JasperReports Server. If you plan to use the JasperReports Library directly in your application you will also need to add the configuration to your application via the JasperReports Library properties file.

Configuring iReport Designer

iReport Designer allows you to add a data source for each BDB database you want to access. To define a new data source follow these steps:

1. Go to the "Data" menu and select "Connections/Data Sources". In the resulting window press the "New" button. The "Creation of a new datasource" window will appear.

   

2. Select "Oracle Berkeley DB Connection" from the list and press "Next".

    

3. In the resulting window specify any name you want as the connection name. Press the "Browse" button next to the Environment field and select your Berkeley DB environment. The distribution includes a sample database at {install_dir}/samples/dpl/baseball_db_dpl.

   

4. Set the Mode to match your database. If you are using the Direct Persistence Layer be sure to set the mode appropriately.

    

5. If you are using DPL you must provide the name of the EntityStore to use.

    

6. If you are using the base API and are using serialized classes you need to specify the name of the database that holds serialized class catalog. You do not need to do this if all the Objects you want to access use either primitive or custom bindings.

    

7. When you have defined the connection you need to make sure it works. Press the "Test" button. The following window should appear. If it doesn't double check that the environment was set correctly.

   

8. Once the connection test works, press the "OK" button to close the test results, and press "Save" in the "Connections properties" window. The new data source should appear at the bottom of the list of defined data sources and should be the default.

   

9. Close the data sources window

Your Berkeley DB database is now ready to use with iReport Designer. If you have additional Berkeley DB databases you want to use, add them by repeating these steps. Be sure to give each database connection a unique name. You can switch between the databases by using the drop down list of defined data sources in the iReport Designer tool bar.

Configuring JasperReports Server

JasperReports Server allows you to define custom data sources via the administrator view of the repository. To define a new data source in JasperReports Server follow these steps:

1. Log in to JasperReports Server as an administrator.

    

2. Go to the "View" menu and select "Repository".

    

3. When the repository view comes up select the "Data Sources" node in the folder tree.
4. Go to the "New Resource" icon and select "Data Source" in the drop down menu, as shown below.

   

5. The list of defined data source types will appear. Select "Oracle Berkeley DB" and press "Next>>".

   

6. Fill in the data source definition. Set the "Name" and "Label" fields to whatever you want. The name is used internally to JasperReports Server and can not contain any white space.

   

   The "Path To Database Environment" field is mandatory. If you are using the Direct Persistence Layer (DPL) you need to specify the Entity Store Name, and if you are using the base API and serialization, you need to specify the Clase Database Name. The remaining fields are optional. Note that the database environment path is the path on the server, not a client machine. For the meaning of the rest of the fields see the section on configuring JasperReports Library below.

Configuring JasperReports Library

When you deploy your reports inside your application, you will need to tell the JasperReports Library how to connect to your Oracle Berkeley DB database(s). You can do this either by embedding the connection details inside of every report or by placing it inside your jasperreports.properties file. The later method is strongly recommended.

To specify the connection information you need at a minimum to specify where the database environment can be found. If you are using the base API and serialization for bindings you also need to specify the name of the database that holds class serialization information. If you are using the Direct Persistence Layer you need to specify the name of the entity store to use.

A sample jasperreports.properties file that defines a Berkeley DB database that uses serialization and the base API would contain the lines

Using Oracle Berkeley DB With iReport Designer

Creating a report that uses a Berkeley DB database is easy with iReport Designer. First follow the direction above to install the plugin with iReport Designer. Once that is done just follow these steps.

1. In iReport Designer, go to the "File" menu and select "New Document".

    

2. A "Report properties" window will appear. Give the report any name and other settings you want. Press "OK" when done.

    

3. You should now be editing a new, empty report.

   

4. Go to the "Data" menu and select "Report Query".

    

5. Set the Query language to "bdb". The Query language is set via the drop down list in the upper right corner of the Report Query Window.

   

6. Type in the query for the report. See the section titled "Query Language" for information on the query syntax used. As an example, if you use the included DPL Baseball database (available at {install_dir}/samples/dpl/baseball_db_dpl) the simple query "Team" will return all the Team entities.

    

7. After typing your query press the "Read Fields" button. If your query is valid all the returned data will be automatically mapped to query fields and added to your report.

   

8. Press "OK" to save your query. Look at the "Document structure" panel of iReport Designer and expand the "Fields" section. You should see all of the available fiel

At this point you can author and test your report just like one that uses any other type of data source.

Query Language

The basic syntax for any query that you add to a report is the same regardless of whether the base API or the Direct Persistence Layer is being used. The syntax is either

or

The actual syntax of how to specify a Name and a SearchKey depends on the API being used, and is described in the following sections.

Querying The Direct Persistence Layer

When using the Direct Persistence Layer a PrimaryName refers to the Entity defined in the database to return. A SecondaryName is the name of a secondary key defined on the Entity the PrimaryName refers to.

If you just specify the Entity or the Entity and one or more secondary indices then all the objects contained in that Entity or index are returned. If you want to filter for certain Entities then you need to specify a SearchKey. If you specify a SearchKey on the primary Entity then all the Entities that match are returned. If you specify a SearchKey on a single secondary index then all the Entities that are contained in that index and match the specified search are returned. Finally, if you specify multiple secondary indices and SearchKeys, Entities that match all the specified conditions match. (Berkeley DB only supports "AND" style queries on multiple indices.)

DPL Search Keys

A search key can either specify an exact value to search for or a range of values. To search for a single value just specify that value as the search key. To search for a range of values the syntax is fromValue-;toValue-. Append a minus sign "-" to either the from or to search key to perform an exclusive search; by default all searches are inclusive.

Depending on the data type of the Entity or secondary index, the value in a search key can be a simple value (a Java byte, char, short, int, long, float, double, Byte, Character, Short,Integer, Long, Float, Double, String, Date or BigInteger) or a complex type. A complex type contains one or more named values, where the name of the value is a String and the value is one of the simple types.

When the datatype is a simple type, just specify a value as a String. When the datatype is complex, use

Each field name refers to a single field in the object, and the value is the value to set that field to, as a String. If the field occurs in more than one parent Persistent Object of the Entity, you can disambiguate by specifying which Class the field refers to.

Returned Data

When using DPL every field in the returned Entity can be access via it's name. If the field is a simple type it will be returned as its native Java type. If the field refers to a compound class an object of that class will will be instantiated from the database and returned. You can declare a special field named "_THIS" which will return the actual entity. The contents of Collections and Maps will be similarly restored.

For an object to be restored and returned, it must match the current definition of its class in the store. If the definition has evolved since an object was inserted, an attempt to retrieve it will trigger an exception.

Querying The Base API

When using the base API all objects used as keys and values must be JavaBeans. Only fields in the objects that are exposed as Bean properties will be available inside of a report.

A Berkeley DB database created using the base API does not have any metadata about the types of object it contains, or how to bind Objects to database entries. To use a base API database with JasperReports Library you have to embed this information inside the query. You do this by specifying the PrimaryName in the query as

The keyClass and valueClass give the fully qualified class name of the objects used as keys and values in the database. Even when using a secondary database you need to specify the keys and values of the primary, not the secondary. (You specify information about the secondary database keys as part of the secondary search condition, as described below.)

Similarly, the keyBinding and valueBinding indicate how to bind the keyClass and valueClass Objects to database entries. If you are using the default Berkeley DB binding for a Java primitive (such as an int field) set the binding to "primitive". If you use the standard Java serialization binding on your key or value specify a binding of "serial". In this case you must have specified a java class catalog as part of the data source definition or an exception will be thrown. Finally, if either or both the key or value use a custom TupleBinding then set the binding to the fully qualified name of the class that implements the binding.

When using the base API a PrimaryName in the query refers to a PrimaryDatabase to search, and a SecondaryName referes to SecondaryDatabase.

At a minimum a primary database must be specified with an optional search key. When used this way the matching contents of the primary database will be returned. If you specify an optional secondary database, it will be opened against the primary and the entire contents will be returned. If you specify a secondary database and a search key, only objects in the secondary database that match the search key will be returned. If you specify a search key on both the primary database and a secondary, the search on the primary will be ignored.

Base API Database Names

A database in the BDB base API is specified by a file name and an optional database name inside that file. You specify both parts of a DatabaseName using a path like expression of

If you have a BDB database file of data.db and want to access the database named "info" inside it, you would use data.db/info as the name of the database. If you need to specify a path to the file, and their is no named database inside it be sure to terminate the path with a trailing "/".

Base API Search Keys

A search key for the base API can specify either an exact value to search for or that all objects that are greater than or equal to the value should be returned. Since a Berkeley DB database using the base API does not have any metadata about the contents of the database you have to specify information about the type of database being searched and how to bind a database record to the associated object. The basic syntax of a value when using the base API is

where keyClass is the Java class for the key, binding indicates the type of binding being used, and value is the actual value of the key, as a String. The syntax for specifying the actual value is identical as when using the Direct Persistence Layer, so see the section titled "DPL Search Keys" for more information.

By default, only exact matches are returned. If you append a trailing "-" to a value then all database entries with a value greater than or equal to the specified one will be returned.

The key class is the Java class if the key is an Object, or the corresponding class if the key is a primitive type. In other words, if the key is an int field, use a Java Integer instead.

The binding field indicates the type of binding being used. If you are using the default Berkeley DB binding for a primitive type, such an integer, specify a binding of "primitive". If you are using Java Serialization for binding a complex type, set the binding type to "serial". Finally, if you use a custom implementation of TupleBinding then give the fully qualified name of your binding class to use.

Returned Data

Each row in the returned dataset corresponds to a single key/value pair in the database. A top level JavaBean wraps each row, with two accessible fields - "key" and "value". For example, if your key object has a property named "id" then you will access it by declaring a field named "key.id". Similarly, if your value object has a field named "address" you would declare it in the report as "value.address".