hu.netmind.beankeeper
Class Store

java.lang.Object
  hu.netmind.beankeeper.Store

public class Store
extends java.lang.Object

This store class is the entry point to the persistence library. To store, remove or select given objects, just use the appropriate methods.

Constructor Summary

Store(javax.sql.DataSource dataSource)
Instantiate a store.

Store(java.lang.String driverClass, java.lang.String url)
Instantiate a store.

Method Summary

void	close() Close the store, and release all resources.
java.util.List	find(java.lang.String statement) Query an object from the datastore.
java.util.List	find(java.lang.String statement, java.lang.Object[] parameters) Same as find(statement).
java.lang.Object	findSingle(java.lang.String statement) Same as find(statement), but the result should be a single object.
java.lang.Object	findSingle(java.lang.String statement, java.lang.Object[] parameters) Same as find(statement,parameters), but the result should be a single object.
ConfigurationTracker	getConfigurationTracker() Get the configuration tracker for this Store.
EventDispatcher	getEventDispatcher() Get the event dispatcher in which the caller may register listeners.
LockTracker	getLockTracker() Get the lock tracker.
java.lang.Long	getPersistenceId(java.lang.Object obj) Get the persistence id for an object.
PersistenceMetaData	getPersistenceMetaData(java.lang.Object obj) Get the persistence meta-data object for a given object.
TransactionTracker	getTransactionTracker() Get the transaction tracker associated with this store.
void	remove(java.lang.Object obj) Remove the object given.
void	save(java.lang.Object obj) Save the given object to the store.

Methods inherited from class java.lang.Object

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

Constructor Detail

Store

public Store(java.lang.String driverClass,
             java.lang.String url)

Instantiate a store. Note that you should only make one store instance for each datasource you might want to use, all methods are thread-safe, so you can use the single instance in more threads.

Parameters:

driverClass - The driver class to register.

url - The driver's jdbc url (including username and password).

Store

public Store(javax.sql.DataSource dataSource)

Instantiate a store. Note that you should only make one store instance for each datasource you might want to use, all methods are thread-safe, so you can use the single instance in more threads.

Method Detail

close

public void close()

Close the store, and release all resources. This method is automatically invoked as a JVM shutdown hook, so it does not have to be called at all.

getTransactionTracker

public TransactionTracker getTransactionTracker()

Get the transaction tracker associated with this store. The transaction tracker can be used to create transactions, and listen for transactional events.

Returns:

The transaction tracker.

getConfigurationTracker

public ConfigurationTracker getConfigurationTracker()

Get the configuration tracker for this Store.

getLockTracker

public LockTracker getLockTracker()

Get the lock tracker. This tracker can be used to lock and unlock objects for exclusive operations.

getEventDispatcher

public EventDispatcher getEventDispatcher()

Get the event dispatcher in which the caller may register listeners.

getPersistenceId

public java.lang.Long getPersistenceId(java.lang.Object obj)

Get the persistence id for an object. This method always returns a valid id, even if the object is not saved, or otherwise has no persistence id. If the object is later saved, this persistence id is always preserved.
Same as: getPersistenceMetaData(obj).getPersistenceId().

Returns:

A persistence id, and never null.

getPersistenceMetaData

public PersistenceMetaData getPersistenceMetaData(java.lang.Object obj)

Get the persistence meta-data object for a given object. Metadata is always available, even for non-saved objects.

save

public void save(java.lang.Object obj)

Save the given object to the store. The given object's all private non-transient fields will be saved. If the object was not selected from the store, and not yet saved, it will be created in the store, and a unique id will be assigned, so all subsequent calls to save the given object will only modify the already existing instance in store. A few tips:

• Use simple beans. Although this library does not scan methods to determine the attributes to save, it is a good idea to simplify work with them.
• If you do not use simple beans, watch out that your object does not reference unnecessary objects, because if it does, all will be saved/inserted and tracked.
• You CAN use objects which reference other beans though. But beware, that all objects which are directly referenced will be loaded when the parent object loads.
• You CAN use Map, and List types in your beans. Check the documentation.

Note:A save operation is not recursive. It does not traverse the object hierarchy, only saves the object given, and does not save objects referenced, except when referenced object does not exist yet. If a referenced object does not yet exist, it will be inserted into database (and recursively all referenced objects of that object). Implementation note:This class is the intelligent part of the framework, an intentionally so. This is the class that coordinates all other classes, trackers and functions together.

Parameters:

obj - The object to save.

Throws:

StoreException - If save is not successfull.

remove

public void remove(java.lang.Object obj)

Remove the object given. If the object is not stored yet, no operation will take place.

Parameters:

obj - The object to remove.

Throws:

StoreException - If remove is not successfull.

find

public java.util.List find(java.lang.String statement)

Query an object from the datastore. The List returned is a lazy list, the implementation tries to limit the communication with the database layer, as much as possible and pratical. Only parts of the list will be loaded when an item is referenced, not the whole list. Some features of the query language:

find book where book.name='Snow Crash'

The statement always starts with the keyword 'find', and all keywords and parts of the statement not between apostrophs are case in-sensitive.
The second word of the statement determines the class you are trying to find. You can abbreviate the classname (strip the package) if it is unique, but you can use the full name (com.acme.book) if you wish, but then you MUST provide an alias name (see below)
The following parts are all optional. First, there can be a select statement, to specify which objects to select which are instances of given class. If you want to have a where part, the third word should be 'where'. After it there should be an expression almost as in SQL. Parts of the expression can be:

• Member attributes of classes. The class given previously (the target of statement) is always available as declared. If you wish to use other classes, they can be referenced by class (abbreviated or fully declared). For example

  find book where book.author=author and author.birthdate=1959

  Of course Book, and Author classes must exits in the store with given attributes. Note also, that the above statement can be simply written:

  find book where book.author.birthdate=1959

  You can name the classes you are referencing for later use (handy if you must "join" the class with itself):

  find book where book.author=otherbook(book).author and otherbook.name='Snow Crash'

  Here, the "otherbook" does not refer to a class, it is only another name for the class book, and means, that is should be not the same instance as the one referenced with "book".
• "Now" constant: For easy use the current date/time is represented with the special word 'now'. So you can write:

  find movie where movie.startdate > now

  This also means, that attributes named 'now' must be escaped (prefixed with it's table name).
• Constants: Numbers and strings, see examples above. Dates and objects can be given by using the question mark (?), and adding the object as parameters (same as in jdbc).
• The operators: <, >, =, !=, like, is null, not null, is not null. Note however, that not all database backends are required to support all of these. If they are not supported, an exception will be thrown.
• Logical operators: or, and, not. See examples above.
• Grouping with parenthesis. As usual in expressions, you can use grouping:

  find book where ((book.author.firstname='Neal') and (book.author.lastname='Stephenson'))

• Special container operator: contains. These are used in conjunction with container types such as Map and List:

  find book where book.genres contains genre and genre.name='postcyberpunk'

  find author where author.books contains book and book.name='Snow Crash'

  A container operator can not be negated, an exception will be thrown, if the expression would try to do that.
• Special map operator: [, ]. These are used when referencing a Map. Note also, that [] can only contain strings.

  find book where book.metadata['author']=author and author.name='Neal Stephenson

  However, if after a map operator an attribute is referenced, there is a mandatory class specifier:

  find book where book.metadata['author'](author).name='Neal Stephenson

You can also sort the result list with the 'order by' command:

find book order by book.name asc

The order by command takes attributes as aguments. You can give more than one attribute separated by commas. Also you can append 'asc' (ascending) or 'desc' (descending) to mark the direction of sort.

find book order by book.author.name asc, book.name desc

Note, that method will silently return an empty list, if the specified table or one specified in where clause does not exist.
For more detailed information, check the documentation.

Parameters:

statement - The query statement to select.

find

public java.util.List find(java.lang.String statement,
                           java.lang.Object[] parameters)

Same as find(statement). When a statement contains the question mark (?), the object which should be in the place of the mark should be given as parameters (parameters are usually of Date, or custom classes).

Parameters:

statement - The query statement to execute.

parameters - The parameters.

findSingle

public java.lang.Object findSingle(java.lang.String statement,
                                   java.lang.Object[] parameters)

Same as find(statement,parameters), but the result should be a single object.

Parameters:

statement - The query statement to execute.

parameters - The parameters to the statement.

Returns:

The object selected, or null if no such object exists. If the result contains more objects, an arbitrary one is selected.

findSingle

public java.lang.Object findSingle(java.lang.String statement)

Same as find(statement), but the result should be a single object.

Parameters:

statement - The query statement to execute.

Returns:

The object selected, or null if no such object exists. If the result contains more objects, an arbitrary one is selected.