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.)
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
Databind currently contains a single binder which maps to an SQL database.
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.Userwhich 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
usernamewill 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
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.
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),
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:
- 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.
- Connects two search parameters together. AND and OR are currently supported.
- A collection of SearchElement objects (parameters and connectors).
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'
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.
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/).
DisclaimerTHIS 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.