DataBind Developer's Guide

DataBind is a library to simplify the persistance of Java objects to a datastore. A datastore may be a relational database, XML files, or any other type of datastore. Java objects which are persisted do not need to be modified in any way. The only requirement for persisted objects is that they have read and write methods for each field that you would like to persist. The read and write methods are specified at deployment time in an XML file and thus can be any method (in other words they do not have to be getter and setter methods, although this is the preferred method signature.)

Binder

Databind abstracts the concept of a datastore by letting implementation specific classes handle the loading, storing and destruction of data in the datastore. These implementations must all extend from the abstract org.databind.binder.Binder base class.

Databind currently contains a single binder which maps to an SQL database.

Configuration

Databind uses an XML file to configure mappings of objects to the data store. The XML document maps each object to the storage system. The example configuration file (databind.xml) contains a mapping of two views on the same object org.databind.example.User which can be persisted to a MySQL database table.

The first part of the object configuration defines the data from the object which should be persisted:

	<field>
		<name>username</name>
		<type>java.lang.String</type>
		<read-method>getUsername</read-method>
		<write-method>setUsername</write-method>
	</field>

In the example above the database column username will get data from the getUsername() and setUsername() methods of the object. The type element describes what kind of data type the field is. This type must be a fully qualified Java class and must match the type of the argument sent to the setUsername() method.

After defining all of the fields to persist elements specific to the binder implementation are defined.

For SQLBinder (currently the only binder provided) a datasource is defined:

	<datasource>
		<driver>org.gjt.mm.mysql.Driver</driver>
		<url>jdbc:mysql://homer.gallery/test</url>
		<username>databind</username>
		<password></password>
	</datasource>

The SQLBinder provided with DataBind currently required the datasource to be defined in the configuration file. Future versions of DataBind will allow a perdefined datasource to be used.

Next the SQL statements are defined:

	<select-statement>
		<statement>select * from user</statement>
	</select-statement>
	<insert-statement>
		<statement>insert into user (username, name) values (?, ?)</statement>
		<variable>username</variable>
		<variable>name</variable>
	</insert-statement>
	<update-statement>
		<statement>update user set name = ? where username = ?</statement>
		<variable>name</variable>
		<variable>username</variable>
	</update-statement>
	<delete-statement>
		<statement>delete from user where username = ?</statement>
		<variable>username</variable>
	</delete-statement>

The SQLBinder can have one statement for each possible database interaction: select, insert, update and delete. It is only necessary to specify the statements which your object will support (if you will provide read-only access then you should only provide the select statement). Each statement includes the SQL query (written as described in the JDBC PreparedStatement documentation) as well as 0 or more variable elements (Note: The select statement no longer accepts variable elements, instead using a runtime defined SearchElement). The variable elements must be placed in the exact order as they appear in the SQL statement. Each variable corresponds to a field defined previously [author note: In the future it may be possible to define a variable as a method of the object so that a non-persisted field could be used as a variable value. Is this useful?]

DataBind supports multiple views on the same object type. This allows you to provide both a read-only and a read/write view to the same object. You could also use this to provide access to the same object types in different databases.

Using DataBind

To use DataBinder in your Java application you can either create an instance of the BinderManager or you can use the BinderManager.getInstance() method to retrieve a shared instance of the BinderManager. One you have a reference to the BinderManager you should load the BinderManager's configuration by either:

• passing a File to the readConfiguration() method. This file should point to a valid DataBind XML configuration file.
• passing an InputStream to the readConfiguration() method. The InputStream should pull its data from a valid DataBind XML configuration source (whehter it be a file, a URL, or any other source).

Once the BinderManager is configured you can then use the loadData(Object object, SearchElement searchElement), storeData(Object object) and destroyData(Object object) methods to persist your object to the datastore. These methods will find the appropriate data store mapping and will handle the persistance of the data. If you want to use views then you should use the loadData(Object object, SearchElement searchElement, String view), storeData(Object object, String view) and destroyData(Object object, String view) methods.

The searchElement value can be any of the following classes:

org.databind.search.SearchParameter

A name/value pair with an operator. Supported operators can be found in the MatchOperator class and include equals, not equals, less than, greater then, etc.

org.databind.search.SearchConnector

Connects two search parameters together. AND and OR are currently supported.

org.databind.search.SearchGroup

A collection of SearchElement objects (parameters and connectors).

Search Elements

DataBind allows data stores to be searched using a common selection of search objects. Currently DataBind supports SearchParameters which are name/value pairs with an operator, SearchConnector which are AND or OR values, and SearchGroups which are collections of SearchParameters connected with SearchConnectors.

Here is an example of an SQL query:

SearchGroup group = new SearchGroup();
group.add(new SearchParameter("firstname", "Anthony", MatchOperator.EQUALS));
group.add(SearchConnector.AND_CONNECTOR);
group.add(new SearchParameter("lastname", "Eden", MatchOperator.EQUALS));

This would be converted into the following SQL where clause:

where firstname = 'Anthony' and lastname = 'Eden'

Collections

DataBind supports loading individual objects or collections of the same type of object from a data store. To load a collection of objects use the BinderManager.loadData(Object object, Collection collection, SearchElement searchElement) method.

You can also store a collection of objects by using the BinderManager.storeData(Collection collection). All code must be of the same type. The first object in the collection will be used as a prototype.

Acknowledgements

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

This product includes software developed by the JDOM Project (http://www.jdom.org/).

Disclaimer

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, 
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 POSSIBILITY OF SUCH DAMAGE.