Oracle Berkeley DB Java Edition

Description

This package adds support for using Oracle Berkeley DB Java Edition (BDB JE) as a data source within JasperReports. It supports both direct access to a BDB JE database via the base API and access via the Direct Persistence Layer (DPL) of Berkeley DB. The project includes the actual datasource, an iReport plugin to support creating new reports using BDB JE, and a JasperReports Server plugin so you can deploy your reports on the web or schedule their execution and delivery.

Installing

Before you can create or run a report that uses Berkeley DB as a data source, you need to install the BDB jE plugin into iReport or JasperReports Server.

At the time this document was written the NetBeans based version of iReport was still in 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 is straight forward.

1. Copy lib/jasperreports-bdb-je-<version>.jar to iReport's lib directory
2. Copy the Berkeley DB Java Edition library je-<version>.jar to iReport's lib directory
3. Copy all the Entities used by your application to iReport's lib directory
4. Exit and restart iReport for your changes to take effect

Installing into JasperReports Server is also straight forward.

1. Copy the file jasperserver/applicationContext-bdbjeDS.xml to the WEB-INF directory of the JasperReports Server web application.
2. Copy the file jasperserver/bdbje.properties to the WEB-INF/bundles directory of the JasperReports Server web application.
3. Copy the file lib/jasperreports-bdb-je-<version>.jar to the WEB-INF/lib directory of the JasperReports Server web application.
4. Copy the Berkeley DB Java Edition jar je-<version>.jar to the WEB-INF/lib directory of the JasperReports Server web application.
5. Copy your applications Entities into WEB-INF/lib in the JasperReports Server web application.
6. Exit and restart JasperReports Server for your changes to take effect

Configuration

The Oracle Berkeley DB Java Edition 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 are going to use it, typically once for use by iReport and once for use by JasperReports Server or your application.

Configuring iReport

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

1. Go to the "Data" menu and select "Connections/Data Sources". In the resulting window press the "New" button. The "Connections properties" window will appear.

   

2. Select "Oracle BerkeleyDB Java Edition 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 BerkeleyDB enviornment. 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 and have more than one Entity Store in your database you need to provide the name of the Store to use. A typical DPL database has only one Entity Store so you will rarely need to do this.
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 datasource should appear at the bottom of the list of defined datasources and should be the default.

   

9. Close the datasources window

Your BerkeleyDB database is now ready to use with iReport. If you have additional BekeleyDB 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 tool bar.

Configuring JasperReports Server

JasperReports Server allows you to define custom data sources via the administrator's 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 Java Edition" and press "Next>>"

   

6. Fill in the data source definition. The "Name", "Label" and "Path To Database Environment" fields are mandatory, the rest are optional. If you are using the Direct Persistence Layer and have more than one Entity Store in your database, specify the Entity Store to use in the "Entity Store Name" field. If you are using the base API and default serialization of Java classes, specify the name of the class serialization database in the "Class Database Name" field.

   

7. Press "Save" to save your new data source

Your new data source is now available to use with a report in JasperReports Server. If you have more than one database environment you want to use with JasperReports Server define an additional data source for each environment. You need JasperReports Server (Professional or Community Edition) 3.0 or later to use Oracle Berkeley DB Java Edition with JasperReports Server. Earlier versions of JasperReports Server used a different plugin architecture for custom data sources.

Configuring JasperReports

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 and have more than one Entity Store inside the database 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

How To Use With iReport

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

1. In iReport, 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-je".

   

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 and expand the "Fields" section. You should see all of the avaliable fields.

   

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

PrimaryName[[Oracleberkeleydbjavaedition/[=SearchKey | [=SearchKey]]

or

PrimaryName[[Oracleberkeleydbjavaedition/[:SecondaryName[[=SearchKey | [:SecondaryName[[Oracleberkeleydbjavaedition/=SearchKey|=SearchKey]]]*

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. (BerkeleyDB 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[[Oracleberkeleydbjavaedition/[- | [-]];toValue[[Oracleberkeleydbjavaedition/[- | [-]]

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 datatype 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

key=[[Oracleberkeleydbjavaedition/[class. | [class.]]fieldName=value[[Oracleberkeleydbjavaedition/[[class.| []]fieldName=value]*

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 BerkeleyDB 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 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 BerkeleyDB 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 datasource 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 a 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 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 BerkeledyDB 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 tiled "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 BerkeleyDB 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".