net.sf.spif.persistence
Class StorePersister

java.lang.Object
  |
  +--net.sf.spif.StoreChain
        |
        +--net.sf.spif.persistence.StorePersister

public class StorePersister

extends StoreChain

Automatic storage of model objects

The StorePersister is a Store chain which stores to and fetches from a relational storage by automatically matching classes to db tables.

For instance If you wish to persist a Person having a PersonId, a name and an Address, and the address in turn contains a street and a city. All you need to do is create the db tables PERSON(ID,NAME) and ADDRESS(ID,STREET,CITY) and plug this class into you store chain.

You don't even need to match tables exactly to classes, the single table PERSON(ID,NAME,ADDRESSSTREET,ADDRESSCITY) would work just as fine as the two above.

No manual mapping or code generation is needed. When a new type is accessed or store runtime, the object and db tables are matched. The match is cached to be used for later use, which makes the overhead of of negible.

Getting the job done without making a mapping requires that some rules must be followed followed. Generally, tables are named the same as classes and fields the same as columns. This makes the StorePersister a bad choice for most applications developing to legacy or corporate-wide dbs. For projects developing db schemas with the code, however, there is no reason to use different names, and no reason to have humans do work perfectly suited for a machine.

The persistence rules

The goal of the StorePersister is to be as good at making a mapping as a human with absolutely no domain knowledge. Furthermore, is understands edit bubbles as described in Model Centric Rules.

In practice, this means that most objects will map to the db with no human intervention, while some special cases will require special handling, either in form of additional methods in the domain objects or as special classes adding or preparing information to the objects being persisted. When reading the limitations below, keep in mind that using the StorePersister is not a all-or-nothing choice - adding a filtering store chain in front of this which sends the problematis requests to some other persistence mechanism works is straightforward. Also, as you won't invest in any tool-specific mapping, you won't have loosed anything if you find the special cases are becoming the norm and chooses to abandon this class.

These are the rules followed. Keep in mind that a log of the matches done will be produced (as info to a java.util.logging.Logger named by this class name). So it may just be faster to try and see if it does what you want than to read and understand these rules.

• Top-level classes must have a method getId() returning a net.sf.spif.Id subclass named Id.
• There must be a table with the same name as every persistent top-level class
• Each table (top-level or not) table must have an id column as its first column.
• Each persistent property must have a standard getter and setter, the property name must equal the column name. Dependent objects does not need a getter and setter for the id of their owner. Top-level objects may (should) have an unary constructor taking the id as parameter instead of a setId.
• The types exposed by persistent property getters and setters must either be standard Java types (primitives, Strings, Dates etc) or classes having a unary constructor taking a string which is symmetric to the value returned by either method stringValue, or toString if there is no stringValue. Id classes usually supports this.
• Dependent objects can map to their own tables or to columns in the table of the parent. If a dependent object has its own table, the table must have a first field storing the id of the edit bubble, but the dependent object does not need an id field. To map the object to columns in the parent table, append either the name of the class of the dependent object or the name of the property in the owner class which contains the dependent object. That is, if you have a Person having a Point class accessed by get/setLocation(), it will map both to PERSON(ID,POINTX,POINTY) and to PERSON(ID,LOCATIONX,LOCATIONY).
• Collections are mapped as well. They must be accessible by at least a getCollectionpropertyIterator and addCollectionproperty method in the object having the collection. The table containing collection elements are no different from other tabels, the first column stores the id of the owner, and the rest store attributes.
• Colelction tables are named or . So an Order having a collection of Items accessed by getOrdered and addOrdered would require a table named either OrderItems or OrderOrdered.
• Collections containing id's are threated as any other collection, in other words, link tables are required by the store persister to store nary interbubble relations. The first column of the link table is the id of the owner, and the next (usually) is the id of the child. Because the id of the owner is always in the first position, it does not need to be named id. In fact, the column containing the owned id must be named id instead. So a Person having a getChildIterator() and addChild(PersonId) would need a link table PERSONCHILD(PARENTID,ID).
• Note also that collection persistence will perform better if you use the collection implementations in this package instead of the implementations in java.util.

There will not be uncontrolled backwards-incompatible changes to these rules. I.e. restrictions may disappear without notice, but not the other way around.

The current limitations to be aware of:

• Properties typed as interfaces or supertypes will not work, as the type of dependent objects (collection or not) is determined by examining the signature of the accessors.
• Multi-value immutables are not supported. That is, if you would like to have an immutable address you can't because it would require instantiation by a multivalue constructor like (Address(String street,String city). The best thing you can do for now is to provide setters for each property but mark the as forbidden in the JavaDoc.
• Bidirectiona links are not directly supported. That is, they must either be threated as two different one-way links or stored manually by adding a store chain class for it.
• Collections without link tables are not supported. However, there is an important advantage with link tables: It's semantics maps easier to those of objects. If the link is one-way you do not need to change the target object to change a link. But without link tables you still have to update the receiver table (and thus lock the object).
• Some work has been done to support overriding of functionality, but this is not recommended to use in it's scurrent condition unless you wish to read and understand all the code in this package.

The three first of these limitations will be addressed in the next major release of Spif.

I am sure you can live with these limitations and follow the lead of the lazy!

This store will not currently propagate store chain requests (though this may well be implemented later).

Version:

$Id: StorePersister.java,v 1.5 2003/02/13 22:13:44 bratseth Exp $

Author:

Jon S Bratseth

Field Summary

protected static java.util.logging.Logger

log

Fields inherited from class net.sf.spif.StoreChain

chained

Constructor Summary

StorePersister(java.lang.String dataSourceName)
Creates an instance

Method Summary

protected TypePersister	createTypePersister(java.lang.Class type, java.sql.Connection connection) Creates a type persister for a given id class.
java.lang.Object	get(Id id, boolean writable) Returns an object from the store.
Id	put(Id id, java.lang.Object object) Puts an object in the store.
protected boolean	reentrantAccess() This defends agains cases where a getter invocation on a store object causes a new access for a store object.
boolean	remove(Id id) Removes an object.

Methods inherited from class net.sf.spif.StoreChain

clear, equals, getChained, getChained, getChained, hashCode, setChained

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

protected static java.util.logging.Logger log

Constructor Detail

StorePersister

public StorePersister(java.lang.String dataSourceName)

Creates an instance

Parameters:

dataSourceName - the name of the dataSource to obtain db connections from. This class gets jndi connections from the InitialContextFactory which you'll have to initialize first.

Method Detail

get

public java.lang.Object get(Id id,
                            boolean writable)

Description copied from class: StoreChain

Returns an object from the store.

This default implementation just forwards to the chained. for (optional) use by subclasses.

Overrides:

get in class StoreChain

Parameters:

id - the id of the object to return

Returns:

the object, or null if the object could not be retrieved or if the input id was null

put

public Id put(Id id,
              java.lang.Object object)

Description copied from class: StoreChain

Puts an object in the store. The objects may be new, or previously acquired by getting writeable. It is an error to attempt to put an existing object not previously acquired by getting writeable.

This default implementation just forwards to the chained. for (optional) use by subclasses.

Overrides:

put in class StoreChain

Parameters:

id - the id of the object to put. May be null

object - the object to put. May be null

Returns:

the id of this object. This will usually be (and is in this default implementation) the input id, unless the given id is null and there is an id generating service on the store chain

remove

public boolean remove(Id id)

Description copied from class: StoreChain

Removes an object. Does nothign if the object does not exist.

This default implementation just forwards to the chained. for (optional) use by subclasses.

Overrides:

remove in class StoreChain

Parameters:

id - the id of the object to remove

Returns:

true if the object did not exists

reentrantAccess

protected boolean reentrantAccess()

This defends agains cases where a getter invocation on a store object causes a new access for a store object. Such implicit accesses should be avoided (but I admit I do it myself sometimes). Anyway, this check allows us to operate correctly on implicit accesses anyway by returning null if we access the store when we are allready in the store.

createTypePersister

protected TypePersister createTypePersister(java.lang.Class type,
                                            java.sql.Connection connection)
                                     throws java.sql.SQLException

Creates a type persister for a given id class. Override to use custom persisters for certain types.

java.sql.SQLException