com.sptci.prevayler
Class PrevalentSystem

java.lang.Object
  com.sptci.prevayler.StorageSystem
      com.sptci.prevayler.IndexSystem
          com.sptci.prevayler.ConstraintSystem
              com.sptci.prevayler.SearchSystem
                  com.sptci.prevayler.ObjectGraphSystem
                      com.sptci.prevayler.PrevalentSystem

All Implemented Interfaces:

AbstractDatabase<PrevalentObject>, DatabaseSystem, Serializable

public class PrevalentSystem
extends ObjectGraphSystem

A base class for prevalent systems that will be managed by Prevayler and wrapped in a Prevayler instance. This class may be sub-classed to extend features or customise the implementation of the various methods used to implement the rules of the database engine. We hope that you will not need to sub-class this instance.

Note that all the methods provided by this class ensure encapsulation of the data stored in the prevalent system. All objects stored are clones of the prevalent objects passed in, and all prevalent object instances returned by transactional or query methods are clones of the instances stored in the system. This does increase the memory footprint of the system, however it is more critical to preserve encapsulation of data. To improve performance client code may utilise various caching products to cache the results of query execution to reduce the number of copies of the prevalent objects in the JVM heap space.

.

© Copyright 2008 Sans Pareil Technologies, Inc.

Version:

$Id: PrevalentSystem.java 22 2008-11-24 19:04:25Z sptrakesh $

Author:

Rakesh Vidyadharan 2008-05-22

See Also:

PrevalentSystemFactory, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class com.sptci.prevayler.StorageSystem

StorageSystem.TaskQueue

Field Summary

private static String	META_DATA The name of the meta data field in PrevalentObject.
private static String	OBJECT_ID The name of the object id field in PrevalentObject.
private static long	serialVersionUID

Fields inherited from class com.sptci.prevayler.SearchSystem

CLASS_FIELD, DOCUMENT_ID_FIELD, OBJECT_ID_FIELD, reader, SAVE_COUNT, searcher, SEPARATOR_CHAR, writer

Fields inherited from class com.sptci.prevayler.StorageSystem

logger

Constructor Summary

protected

PrevalentSystem() Default constructor.

Method Summary

protected PrevalentObject	add(PrevalentObject object, Date executionTime) Add a new prevalent object to the prevalent system.
int	count(Class cls) Return the total number of instances of the specified type in the prevalent system.
PrevalentObject	delete(PrevalentObject object, Date executionTime) Delete the specified prevalent object from the prevalent system.
Collection<PrevalentObject>	fetch(Class cls, long start, long end) Fetch the prevalent objects in the specified range of data.
PrevalentObject	fetch(Class cls, Object oid) Fetch the prevalent object of the specified type with the specified object id from the prevalent system.
Collection<PrevalentObject>	fetch(Class cls, String field, Object object) Fetch the prevalent object(s) of the specified cls type which has the specified object as the value of the specified field.
Collection<PrevalentObject>	fetchIntersection(Class cls, Map<String,?> parameters) Fetch the prevalent object(s) of the specified cls type which has the specified indexed field values.
Collection<PrevalentObject>	fetchUnion(Class cls, Map<String,?> parameters) Fetch the prevalent object(s) of the specified cls type which has the specified indexed field values.
PrevalentObject	save(PrevalentObject object, Date executionTime) Save the specified prevalent object to the prevalent system.
Collection<PrevalentObject>	search(org.apache.lucene.search.Query query, org.apache.lucene.search.Filter filter, int count, org.apache.lucene.search.Sort sort) Execute the specified lucene query and return the collection of matching prevalent objects.
protected void	setOid(PrevalentObject object) Set the PrevalentObject.objectId field to a new value if not already set.
protected PrevalentObject	update(PrevalentObject object, Date executionTime) Update the specified prevalent object in the prevalent system.
protected void	updateOrdinaryField(PrevalentObject prevalentObject, Field field, Object source, Object destination) Update an ordinary field (non prevalent object or collection).

Methods inherited from class com.sptci.prevayler.ObjectGraphSystem

compose, decompose, update

Methods inherited from class com.sptci.prevayler.SearchSystem

index, remove, search

Methods inherited from class com.sptci.prevayler.ConstraintSystem

checkFields, checkUnique, checkUnique, indexClass, indexFields, preAdd, preDelete, preDelete

Methods inherited from class com.sptci.prevayler.StorageSystem

generateOid, getIndexStorage, getIndexStorage, getPrimaryStorage, getPrimaryStorage, getReferenceStorage, getReferenceStorage, getRelationStorage, getRelationStorage, getTaskQueue

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

OBJECT_ID

private static final String OBJECT_ID

The name of the object id field in PrevalentObject.

See Also:

Constant Field Values

META_DATA

private static final String META_DATA

The name of the meta data field in PrevalentObject.

See Also:

Constant Field Values

Constructor Detail

PrevalentSystem

protected PrevalentSystem()

Default constructor.

Method Detail

save

public PrevalentObject save(PrevalentObject object,
                            Date executionTime)
                     throws PrevalentException

Save the specified prevalent object to the prevalent system. Objects not already persistent are added to the system, while already persistent objects are updated.

Parameters:

object - The prevalent object to be saved in the system.

executionTime - The time at which the transaction was executed.

Returns:

The potentially modified prevalent object.

Throws:

PrevalentException - If errors are encountered while adding/updating the object. Errors thrown could indicate constraint violations.

delete

public PrevalentObject delete(PrevalentObject object,
                              Date executionTime)
                       throws PrevalentException

Delete the specified prevalent object from the prevalent system. Processes cascading delete rules if so configured.

Parameters:

object - The prevalent object to delete.

executionTime - The datetime at which the transaction was executed.

Returns:

The deleted object with potential modifications.

Throws:

PrevalentException - If errors are encountered while deleting the prevalent object.

count

public int count(Class cls)

Return the total number of instances of the specified type in the prevalent system.

Parameters:

cls - The type of the prevalent object whose count is desired.

Returns:

The total number of prevalent objects of the specified type.

fetch

public PrevalentObject fetch(Class cls,
                             Object oid)
                      throws PrevalentException

Fetch the prevalent object of the specified type with the specified object id from the prevalent system.

Parameters:

cls - The type of the prevalent object.

oid - The object id for the prevalent object to retrieve.

Returns:

The prevalent object instance. Returns null if no such object is stored in the prevalent system.

Throws:

PrevalentException - If errors are encountered while reconstituting the prevalent object.

See Also:

ObjectGraphSystem.compose(com.sptci.prevayler.PrevalentObject)

fetch

public Collection<PrevalentObject> fetch(Class cls,
                                         String field,
                                         Object object)
                                  throws PrevalentException

Fetch the prevalent object(s) of the specified cls type which has the specified object as the value of the specified field.

Note: Only indexed fields are searched. If the specified field is not indexed, this method returns an empty collection.

Parameters:

cls - The type of prevalent object to query for.

field - The name of the field in the prevalent object using which the results are to be queried.

object - The value of the field.

Returns:

The collection of prevalent objects who have the specified object in the field specified. Returns an empty collection if no results are found.

Throws:

PrevalentException - If errors are encountered while reconstituting the prevalent objects being returned.

fetchUnion

public Collection<PrevalentObject> fetchUnion(Class cls,
                                              Map<String,?> parameters)
                                       throws PrevalentException

Fetch the prevalent object(s) of the specified cls type which has the specified indexed field values. The results contain a union of the matching objects.

Note: Only indexed fields are searched. If the specified field(s) are not indexed, this method ignores those field(s).

Parameters:

cls - The type of prevalent object to query for.

parameters - The map of parameters to use to filter the prevalent instances.

Returns:

The collection of prevalent objects that matches the specified parameters.

Throws:

PrevalentException - If errors are encountered while reconstituting the prevalent objects being returned.

See Also:

AbstractDatabase.fetch( Class, String, Object )

fetchIntersection

public Collection<PrevalentObject> fetchIntersection(Class cls,
                                                     Map<String,?> parameters)
                                              throws PrevalentException

Fetch the prevalent object(s) of the specified cls type which has the specified indexed field values. The results contain an intersection of the matching objects.

Note: Only indexed fields are searched. If the specified field(s) are not indexed, this method ignores those field(s).

Parameters:

cls - The type of prevalent object to query for.

parameters - The map of parameters to use to filter the prevalent instances.

Returns:

The collection of prevalent objects that matches the specified parameters.

Throws:

PrevalentException - If errors are encountered while reconstituting the prevalent objects being returned.

See Also:

AbstractDatabase.fetch( Class, String, Object )

fetch

public Collection<PrevalentObject> fetch(Class cls,
                                         long start,
                                         long end)
                                  throws PrevalentException

Fetch the prevalent objects in the specified range of data. This method supports display of paginated view of the prevalent objects of the type specified. Note that the objects are returned in insertion order.

Parameters:

cls - The type of prevalent object to retrive.

start - The starting index (inclusive) from which to fetch the prevalent objects.

end - The ending index (exclusive) to which to fetch the prevalent objects.

Returns:

The collection of prevalent objects. Returns an empty collection if there are no objects in the specified range.

Throws:

PrevalentException - If errors are encountered while fetching the objects.

See Also:

PrimaryStorage.get( long, long )

search

public Collection<PrevalentObject> search(org.apache.lucene.search.Query query,
                                          org.apache.lucene.search.Filter filter,
                                          int count,
                                          org.apache.lucene.search.Sort sort)
                                   throws PrevalentException

Execute the specified lucene query and return the collection of matching prevalent objects.

Notes:

• We use built-in lucene analysers which apply a lower-case filter to the input content. Hence make sure that you specify only lower-case search clauses in your query.
• The results may be restricted to only instances of specific prevalent classes by adding Term clauses for the class. The Document instance for a prevalent object contains a class Field which contains the fully qualified class name of the prevalent object.

Parameters:

query - The lucene query that is to be executed to find matching prevalent object instances.

filter - The filter to apply to restrict the query results.

count - The maximum number to top hits for the search to return.

sort - The sort criteria to use for the results.

Returns:

The collection of matching instances or an empty collection.

Throws:

PrevalentException - If errors are encountered while reconstituting the prevalent objects being returned.

add

protected PrevalentObject add(PrevalentObject object,
                              Date executionTime)
                       throws PrevalentException

Add a new prevalent object to the prevalent system. It is recommended that you over-ride the methods invoked by this method rather than this method itself.

Parameters:

object - The object to be added to the system.

executionTime - The time at which the transaction was executed.

Returns:

The potentially modified object passed in.

Throws:

PrevalentException - If errors are encountered while adding the object.

See Also:

ConstraintSystem.preAdd(com.sptci.prevayler.PrevalentObject), StorageSystem.getPrimaryStorage(java.lang.Class), ObjectGraphSystem.decompose(com.sptci.prevayler.PrevalentObject, java.util.Date), setOid(com.sptci.prevayler.PrevalentObject), SearchSystem.index(com.sptci.prevayler.PrevalentObject)

update

protected PrevalentObject update(PrevalentObject object,
                                 Date executionTime)
                          throws PrevalentException

Update the specified prevalent object in the prevalent system. If the specified object does not represent a persistent instance, it is added to the system. In this regard it is possible to directly use this method always instead of add(com.sptci.prevayler.PrevalentObject, java.util.Date).

Note that this method invokes itself recursively to update any objects in the object graph that represent prevalent objects that also need updating.

Parameters:

object - The prevalent object to update in the system.

executionTime - The datetime at which the transaction was executed.

Returns:

The potentially modified prevalent object. The returned object is modified only if the object is added to the system and when datastore object id is in use.

Throws:

PrevalentException - If errors are encountered while updating (or adding) the prevalent object.

See Also:

fetch( Class, Object ), add(com.sptci.prevayler.PrevalentObject, java.util.Date), ObjectGraphSystem.update( Field, PrevalentObject, Date )

setOid

protected void setOid(PrevalentObject object)
               throws PrevalentException

Set the PrevalentObject.objectId field to a new value if not already set.

Parameters:

object - The prevalent object whose primary key is to be set.

Throws:

PrevalentException - If errors are encountered while setting the privary key field.

See Also:

StorageSystem.generateOid(com.sptci.prevayler.PrevalentObject)

updateOrdinaryField

protected void updateOrdinaryField(PrevalentObject prevalentObject,
                                   Field field,
                                   Object source,
                                   Object destination)
                            throws IllegalAccessException,
                                   InvocationTargetException

Update an ordinary field (non prevalent object or collection). De-index and re-index the field value if necessary.

Parameters:

prevalentObject - The prevalent object that is being updated.

field - The field in the prevalent object that is being updated.

source - The new value that is being set.

destination - The old value in the field.

Throws:

IllegalAccessException - Reflection error while setting field.

InvocationTargetException - Reflection error while setting field.