| java.lang.Object
 hu.netmind.persistence.Store
| Store | | public class Store (Code) | | This store class is the entry point to the persistence library. To
store, remove or select given objects, just use the appropriate
method.
author:
Brautigam Robert
version:
Revision: $Revision$ |
| Method Summary | |
| public void | close()
Close the store, and release all resources. | | void | commit(Transaction transaction)
Commit a transaction. | | public List | find(String statement)
Query an object from the datastore. | | public List | find(String statement, Object[] parameters)
Same as find(statement). | | List | find(String statement, Object[] parameters, TimeControl timeControl, Map unmarshalledObjects)
This method in addition to all usual parameters can define the
exact time of the query with the timeControl parameter. | | SearchResult | find(Transaction transaction, QueryStatement stmt, Limits limits)
Internal raw loading. | | SearchResult | find(QueryStatement rawStmt, Limits limits, Map unmarshalledObjects)
Internal loading. | | public Object | findSingle(String statement, Object[] parameters)
Same as find(statement,parameters), but the result should be
a single object.
Parameters:
statement - The query statement to execute.
Parameters:
parameters - The parameters to the statement. | | public Object | findSingle(String statement)
Same as find(statement), but the result should be
a single object.
Parameters:
statement - The query statement to execute. | | protected StoreContext | getContext()
Get context. | | public EventDispatcher | getEventDispatcher()
Get the event dispatcher in which the caller may register
listeners. | | public LockTracker | getLockTracker()
Get the lock tracker. | | public Long | getPersistenceId(Object obj)
Get the persistence id for an object. | | public PersistenceMetaData | getPersistenceMetaData(Object obj)
Get the persistence meta-data object for a given object. | | public TransactionTracker | getTransactionTracker()
Get the transaction tracker associated with this store. | | public void | remove(Object obj)
Remove the object given. | | void | rollback(Transaction transaction)
Rollback a transaction. | | public void | save(Object obj)
Save the given object to the store. |
| Store | | public Store(String driverClass, String url)(Code) | | 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.
Parameters:
url - The driver's jdbc url (including username and password). |
| Store | | public Store(DataSource dataSource)(Code) | | 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.
|
| close | | public void close()(Code) | | 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.
|
| commit | | void commit(Transaction transaction)(Code) | | Commit a transaction. This method is necessary, because on the
end of a transaction, the store must set all persistence_start
and persistence_end date/serials to the actual close-serial
of transaction.
|
| find | | public List find(String statement)(Code) | | 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 List find(String statement, Object[] parameters)(Code) | | 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:
parameters - The parameters. |
| find | | List find(String statement, Object[] parameters, TimeControl timeControl, Map unmarshalledObjects)(Code) | | This method in addition to all usual parameters can define the
exact time of the query with the timeControl parameter. If the
query is a historical query, this control will be overridden.
Parameters:
statement - The query statement to execute.
Parameters:
parameters - The parameters.
Parameters:
timeControl - The exact default time of the query. |
| findSingle | | public Object findSingle(String statement, Object[] parameters)(Code) | | Same as find(statement,parameters), but the result should be
a single object.
Parameters:
statement - The query statement to execute.
Parameters:
parameters - The parameters to the statement. The object selected, or null if no such object exists. Ifthe result contains more objects, an arbitrary one is selected. |
| findSingle | | public Object findSingle(String statement)(Code) | | Same as find(statement), but the result should be
a single object.
Parameters:
statement - The query statement to execute. The object selected, or null if no such object exists. Ifthe result contains more objects, an arbitrary one is selected. |
| getEventDispatcher | | public EventDispatcher getEventDispatcher()(Code) | | Get the event dispatcher in which the caller may register
listeners.
|
| getLockTracker | | public LockTracker getLockTracker()(Code) | | Get the lock tracker. This tracker can be used to lock and unlock
objects for exclusive operations.
|
| getPersistenceId | | public Long getPersistenceId(Object obj)(Code) | | 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().
A persistence id, and never null. |
| getPersistenceMetaData | | public PersistenceMetaData getPersistenceMetaData(Object obj)(Code) | | Get the persistence meta-data object for a given object. Metadata
is always available, even for non-saved objects.
|
| getTransactionTracker | | public TransactionTracker getTransactionTracker()(Code) | | Get the transaction tracker associated with this store. The transaction
tracker can be used to create transactions, and listen for transactional
events.
The transaction tracker. |
| remove | | public void remove(Object obj)(Code) | | 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. |
| rollback | | void rollback(Transaction transaction)(Code) | | Rollback a transaction. Rollback has to only unlock objects
the transaction carries, and call the database rollback.
|
| save | | public void save(Object obj)(Code) | | 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. |
|
|