A simple O/R mapper
This is a very simple O/R mapper. It is not intended to be compared to real O/R mapper. It is mainly designed to ease the use of JDBC in your applications.
The examples discussed here are taken from jzForum. You can download the entire source at . The source code is located in the or and manager packages.
Getting started
Let's start by writing our first object:
package org.jzonic.forum.or;
import java.util.List;
import org.jzonic.core.sql.*;
public class ForumDO extends PersistentObject {
private String name;
private String description;
private String authorID;
private long created;
private List categories;
public ForumDO() {
super( new PKField("FORUMID"));
}
// the getter and setter are not shown here
}
Your object must extend the class PersistentObject. This base class provides a few methods that you can override but actually you do not have to if you follow these rules:
1. the primary key must be of type long
2. the tablename is the same as your object name
3. every attribute in your object has the same name as the field in the table
4. all fields in your object are mapped to a field in the table
5. the primary key is called ID in the table.
If you do not follow these rules then this is what you need to do.
1. The primary key of type long
There is no exception to this rule
2. The tablename
If you have a different tablename then override the method getTableName() like this:
public String getTableName() {
return "T_FORUMS";
}
3. All attribute names matches the fields in your table
If the fields have a different name then override the method public Map getFieldMapping() like this:
public Map getFieldMapping() {
Map retValue = new HashMap();
// object attribute name and then field name
retValue.put("description","FORUM_DESCR");
return retValue;
}
Add every attribute that has a different field name
4. All attributes are mapped
Like in the example above the categories are not mapped to the table. The categories are loaded on request when the forum is loaded. So the categories must not be mapped to the table. In order to not map this attribute
use the method public List getTransientFields() like this:
public List getTransientFields() {
List retValue = new Vector();
retValue.add("categories");
return retValue;
}
These fields are considered transient and will be ignored.
5. The primary key has a different name
Then use the constructor like in the example above and define the name:
public ForumDO() {
super( new PKField("FORUMID"));
}
What you can doNow that you have your persistent object you are ready to use the PersistentManager.
The following will walk through all methods that are supported along with an example.
Getting all objects
public List findAll(Class clazz) throws PersistentManagerException
Returns a list of all objects found for the class. The sql statement is:
select * from TABLENAME
PersistentManager manager = new PersistentManager();
List all = manager.findAll(ForumDO.class)
public List findAll(Class clazz,String whereClause)
The same as above but you can also define an additional where clause. The sql will be:
select * from TABLENAME whereClause
PersistentManager manager = new PersistentManager();
List all = manager.findAll(ForumDO.class,"where forumid < 100");
Getting a specific object
public PersistentObject find(Class clazz,String whereClause) throws PersistentManagerException
This method returns one object
PersistentManager manager = new PersistentManager();
ForumDO forum = (ForumDO)manager.find(ForumDO.class,"where forumid=1");
public PersistentObject findByPK(Class clazz,long id) throws PersistentManagerException
The method returns one object if found that has the primary key equals the id passed over.
PersistentManager manager = new PersistentManager();
ForumDO forum = (ForumDO)manager.find(ForumDO.class,20);
Deleting an objectThe first method is used when you want to delete more than one object at a time. You can simply define the where clause that will be used.
public void delete(Class clazz,String whereClause) throws PersistentManagerException
Exmaple:
PersistentManager manager = new PersistentManager();
manager.delete(ForumDO.class,"where forumid > 100");
The next method is used to delete one object. The where clause will be build with the primary key.
public void delete(PersistentObject pobj) throws PersistentManagerException
Example:
PersistentManager manager = new PersistentManager();
manager.delete(forum);
Adding a new objectIn order to save a new object you can use the insert method.
public long insert(PersistentObject pobj) throws PersistentManagerException
Example:
PersistentManager manager = new PersistentManager();
long id = manager.insert(forum);
Updating an existing objectIn order to update an existing object use the following method:
public void update(PersistentObject pobj) throws PersistentManagerException
Example:
PersistentManager manager = new PersistentManager();
manager.update(obj);
How to install itThis sql package depends on a connection pool that is provided by the service provider. The services are defined in a file called services.xml which must be in your classpath.
Example:
<service name="CP" code="org.jzonic.core.sp.services.ConnectionPoolManager">
<attribute name="jdbcUrl" type="java.lang.String" value="jdbc:hsqldb:hsql://localhost:1477"/>
<attribute name="user" type="java.lang.String" value="sa"/>
<attribute name="password" type="java.lang.String" value=""/>
<attribute name="driver" type="java.lang.String" value="org.hsqldb.jdbcDriver"/>
<attribute name="validationQuery" type="java.lang.String" value="select * from FORUM where 1=2"/>
<method name="getPool"/>
</service>
If you want to use hypersonic as embedded database (like the mentioned jzForum) then you need to do two simple steps. First make sure that the database is in your classpath. Next step is to define a service that will start your hypersonic database on startup:
<service name="database" code="org.jzonic.core.sp.services.HypersonicDB">
<attribute name="port" type="int" value="1477"/>
<attribute name="wait" type="long" value="5000"/>
<attribute name="databaseName" type="java.lang.String" value="ForumDB"/>
<method name="startDatabase"/>
<shutdown>
<method name="shutdownDatabase">
<parameter type="java.lang.String" value="ForumDB"/>
</method>
</shutdown>
<load-on-startup/>
</service>
Please change the name of your database and replace the ForumDB entries. Now you have a hypersonic database that will be started automatically when your application is started and you have also defined the connection. It is that simple.
|
