com.googlecode.n_orm

Interface PersistingElement

All Superinterfaces:

Comparable<PersistingElement>, Serializable

public interface PersistingElement
extends Comparable<PersistingElement>, Serializable

Persisting elements are elements that can be stored and retrieved from a SimpleStore. To make a class persisting, do not implement this interface, but rather declare the annotation Persisting.

See Also:

Persisting

Field Summary

Fields

Modifier and Type	Field and Description
static Class<?>[]	PossiblePropertyTypes The list of possible types for simple properties (including keys).
static long	serialVersionUID

Method Summary

Modifier and Type	Method and Description
void	activate(String... families) Retrieves information from the store and put it into this persisting element.
void	activateColumnFamily(String name) Activates a given column family (does not activate included persisting elements).
void	activateColumnFamily(String name, Object from, Object to) Activates a given column family (does not activate included persisting elements).
void	activateColumnFamilyIfNotAlready(String name) Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method).
void	activateColumnFamilyIfNotAlready(String name, long lastActivationTimeoutMs) Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method).
void	activateColumnFamilyIfNotAlready(String name, long lastActivationTimeoutMs, Object from, Object to) Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method).
void	activateColumnFamilyIfNotAlready(String name, Object from, Object to) Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method).
void	activateIfNotAlready(long lastActivationTimeoutMs, String... families) Retrieves information that have not been activated yet from the store and put it into this persisting element.
void	activateIfNotAlready(String... families) Retrieves information that have not been activated yet from the store and put it into this persisting element.
void	addPersistingElementListener(PersistingElementListener listener) Adds a listener to this persisting element.
int	compareTo(PersistingElement rhs) If instanciated classes are different, class names are compared, in the other case, the result of getIdentifier() are compared.
void	delete() Deletes rows representing this persisting element in the store.
void	deleteNoCache() Deletes rows representing this persisting element in the store.
boolean	equals(Object rhs) To be equal, two persisting elements must implement the same class and have the same identifier, no matter they have same values for properties and column families.
boolean	exists() Checks whether the row representing this persisting element is known to exist in the store avoiding as much as possible to query the data store.
boolean	existsInStore() Checks whether the row representing this persisting element exists in the store.
void	flush() Flushes any outgoing request pending on a write-retention store.
PersistingElement	getCachedVersion() If an element with the same id as this element exists in the cache, returns the element from the cache, otherwise returns this element which will be placed in the cache.
Collection<ColumnFamily<?>>	getColumnFamilies() The list of all ColumnFamily held by this persisting element.
ColumnFamily<?>	getColumnFamily(Object collection) The the ColumnFamily held by this persisting element corresponding to the object stored by the object as a column family.
ColumnFamily<?>	getColumnFamily(String columnFamilyName) The the ColumnFamily held by this persisting element with the given name.
String	getFullIdentifier() Same result as getIdentifier(), but postfixed with the name of the class instanciated by this persisting element.
String	getIdentifier() The identifier for this persisting element.
List<Field>	getKeys() The list of keys for this persisting element.
com.googlecode.n_orm.PropertyManagement.PropertyFamily	getPropertiesColumnFamily() The ColumnFamily used to store properties.
Store	getStore() The store used for this persisting element.
String	getTable() The table used to store this persisting element as declared by the Persisting.table() annotation.
boolean	hasChanged() Checks whether this persisting has changed since its last activation.
int	hashCode() The hash code for getIdentifier().
void	removePersistingElementListener(PersistingElementListener listener) Removes a listener to this persisting element.
void	setStore(Store store) Sets the store used for this persisting element.
void	store() Stores the object into the data store designated by getStore().
void	storeNoCache() Store this persisting element as store() but ignoring any write cache.

Field Detail

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

PossiblePropertyTypes

static final Class<?>[] PossiblePropertyTypes

The list of possible types for simple properties (including keys). Other possible types are array of a possible type, persisting elements and classes with only keys.

Method Detail

getStore

Store getStore()

The store used for this persisting element.

setStore

void setStore(Store store)
       throws IllegalStateException

Sets the store used for this persisting element. Note that in most case, you do not need to use this method as stores are automatically discovered.

Parameters:

store - the store to be used

Throws:

IllegalStateException - in case this persisting element already has a store

See Also:

Persisting

getTable

String getTable()

The table used to store this persisting element as declared by the Persisting.table() annotation. If the persisting element inherits another persisting element, only the table for the instanciated class is shown.

getKeys

List<Field> getKeys()

The list of keys for this persisting element. A key is a property annotated with Key. The result is sorted in the order declared by Key.order().

getPropertiesColumnFamily

com.googlecode.n_orm.PropertyManagement.PropertyFamily getPropertiesColumnFamily()

The ColumnFamily used to store properties. A property is a non static, non final, non transient field whose type is one of PossiblePropertyTypes plus persisting elements plus classes with only key properties and no column family, plus arrays of such types. Keys are also readable from this family. The values stored in this column families are the last activated.

See Also:

activate(String...)

getColumnFamilies

Collection<ColumnFamily<?>> getColumnFamilies()

The list of all ColumnFamily held by this persisting element.

getColumnFamily

ColumnFamily<?> getColumnFamily(String columnFamilyName)
                         throws UnknownColumnFamily

The the ColumnFamily held by this persisting element with the given name. The name is the name of the property for the column family, i.e. the non static, non final , non transient Map or Set field.

Throws:

UnknownColumnFamily

See Also:

ColumnFamily.getName()

getColumnFamily

ColumnFamily<?> getColumnFamily(Object collection)
                         throws UnknownColumnFamily

The the ColumnFamily held by this persisting element corresponding to the object stored by the object as a column family. Typical use is myPe.getColumnFamily(myPe.myCf)

Parameters:

collection - the value for the property stored as a column family.

Throws:

UnknownColumnFamily

getIdentifier

String getIdentifier()

The identifier for this persisting element. The identifier is computed from a string representation of all keys of this persisting element separated with KeyManagement.KEY_SEPARATOR. Moreover, the identifier ends with KeyManagement.KEY_END_SEPARATOR.

Throws:

IllegalStateException - in case all keys have not been set

See Also:

ConversionTools.convertToString(Object)

getFullIdentifier

String getFullIdentifier()

Same result as getIdentifier(), but postfixed with the name of the class instanciated by this persisting element.

See Also:

Object.getClass()

hasChanged

boolean hasChanged()

Checks whether this persisting has changed since its last activation. In case this object has not changed, a store() will not trigger any data store request.

See Also:

activate(String...)

store

void store()
    throws DatabaseNotReachedException

Stores the object into the data store designated by getStore(). All non static final or transient fields will be stored into the datastore. All keys have to be set before invoking this operation

This object is stored as a row in table designated by getTable() using the key computed from getIdentifier(). Properties are stored in a column family whose name is given by PropertyManagement.PROPERTY_COLUMNFAMILY_NAME. Column families are stored using their own name (see getColumnFamily(String)), that is the name of the Map or Set fields. Properties and column families which have not changed since last activation of this element are not sent to the store as they are supposed to be already stored.

In case this persisting element inherits another persisting element class, a row with the full identifier is created in the tables for the ancestor class (see Persisting.table()). Properties and column families are not stored in those rows unless stated by the Persisting.storeAlsoInSuperClasses() annotation in the actual class of this persisting element.

To choose a store, you need to supply in the classpath a properties file depending on the nature of the data store you want to use. This property file is to be found in the class path. For a persisting element of a class in package foo.bar, the property file is searched as foo/bar/store.propetries in the complete classpath (in the declared order), then as foo/store.properties, and then directly store.properties. To know how to define the properties file, please refer to your data store supplier. An (naive) example is the Memory data store.

WARNING: any column family change would raise a ConcurrentModificationException during this period in case application is multi-threaded and this element is explicitly shared by threads. In the latter case, the store is retried at most 0.5s per problematic column family. Simplest solution is to search this element in each thread using StorageManagement.getElement(Class, String).
A cleaner mean to solve this issue store calls should be performed within a synchronized section on this or on changed column family:

 synchronized(element.myFamily) { //or merely synchronized(element)
        element.myFamily.add(something);
 }
 

Another way to avoid such problem is to use an instance of ColumnFamily as a column family (but then this cannot be serialized):

  @Persisting class Foo {
        ...
        public java.util.Map <BarK,BarV > element = new MapColumnFamily();
 }
 

Throws:

DatabaseNotReachedException - in case the store cannot store this persisting object (e.g. cannot connect to database)

See Also:

getIdentifier(), SimpleStore

storeNoCache

void storeNoCache()
           throws DatabaseNotReachedException

Store this persisting element as store() but ignoring any write cache. Actually, in case this element has a write cache, request is still sent to the cache, but then flushed immediately so that previous requests regarding this element are merged and sent.

Throws:

DatabaseNotReachedException

delete

void delete()
     throws DatabaseNotReachedException

Deletes rows representing this persisting element in the store.

Throws:

DatabaseNotReachedException

See Also:

store()

deleteNoCache

void deleteNoCache()
            throws DatabaseNotReachedException

Deletes rows representing this persisting element in the store. Actually, in case this element has a write cache, request is still sent to the cache, but then flushed immediately so that previous requests regarding this element are merged and sent.

Throws:

DatabaseNotReachedException

See Also:

store()

getCachedVersion

PersistingElement getCachedVersion()

If an element with the same id as this element exists in the cache, returns the element from the cache, otherwise returns this element which will be placed in the cache. Advantage of this method is to use as much as possible the internal cache, which makes possible to get a possibly already activated object, and get results faster using exists(), activateIfNotAlready(String...), activateColumnFamilyIfNotAlready(String), or activateColumnFamilyIfNotAlready(String, Object, Object).
Typically, this method is used just after the object construction, as soon as keys are valued. An example is the following:
@Persisting public class Element {
@Key private String key;
@Key publi Element(String key) {
this.key = key;
}
}

Element elt = new Element("key").getCachedVersion();

See Also:

Cache

exists

boolean exists()
        throws DatabaseNotReachedException

Checks whether the row representing this persisting element is known to exist in the store avoiding as much as possible to query the data store. A persisting element is said to exist if it has been stored, if it was successfully activated, or if a previous invocation of exists() or existsInStore() returned true. A persisting element is said not to exist if it has never been stored, if it has been unsuccessfully activated (i.e. the data store didn't return any information about the element), or if a previous invocation of exists() or existsInStore() returned false. In other situations, the data store is queried using existsInStore().

Throws:

DatabaseNotReachedException

See Also:

getCachedVersion()

existsInStore

boolean existsInStore()
               throws DatabaseNotReachedException

Checks whether the row representing this persisting element exists in the store. Rows used to store this element in table for its super-classes are not tested.

Throws:

DatabaseNotReachedException

See Also:

store()

activate

void activate(String... families)
       throws DatabaseNotReachedException

Retrieves information from the store and put it into this persisting element. Erases changes done in properties and column families. Properties that are persisting elements are also activated. Column families annotated with ImplicitActivation are also activated. Use activateIfNotAlready(String...) in case you want to avoid re-activating already activated elements of this persisting elements.

Parameters:

families - names of the families to activate even if they are not annotated with ImplicitActivation (see getColumnFamily(String))

Throws:

IllegalArgumentException - in case a given column family does not exists

DatabaseNotReachedException

activateIfNotAlready

void activateIfNotAlready(String... families)
                   throws DatabaseNotReachedException

Retrieves information that have not been activated yet from the store and put it into this persisting element. Column families (the set of simple properties is considered as a column family) that have already been activated by whatever mean (e.g. activateColumnFamily(String, Object, Object)) will not be activated. This means that if a constraint were passed at a previous activation time, it will be preserved.

Parameters:

families - names of the families to activate even if they are not annotated with ImplicitActivation (see getColumnFamily(String))

Throws:

IllegalArgumentException - in case a given column family does not exists

DatabaseNotReachedException

See Also:

getCachedVersion()

activateIfNotAlready

void activateIfNotAlready(long lastActivationTimeoutMs,
                          String... families)
                   throws DatabaseNotReachedException

Retrieves information that have not been activated yet from the store and put it into this persisting element. Column families (the set of simple properties is considered as a column family) that have already been activated by whatever mean (e.g. activateColumnFamily(String, Object, Object)) will not be activated. This means that if a constraint were passed at a previous activation time, it will be preserved.

Parameters:

families - names of the families to activate even if they are not annotated with ImplicitActivation (see getColumnFamily(String))

lastActivationTimeoutMs - the maximum duration (in ms) at which last actual activation was performed. E.g. if last activation happened at 12:00 and method is called at 12:10 while this parameter is set to 3600000 (1 min), activation will happen anyway ; if parameter is set to 40000000, activation will not be performed

Throws:

IllegalArgumentException - in case a given column family does not exists

DatabaseNotReachedException

See Also:

getCachedVersion()

activateColumnFamily

void activateColumnFamily(String name)
                   throws UnknownColumnFamily,
                          DatabaseNotReachedException

Activates a given column family (does not activate included persisting elements).

Parameters:

name - name of the column family

Throws:

UnknownColumnFamily - in case this column family does not exist

DatabaseNotReachedException

See Also:

getColumnFamily(String)

activateColumnFamily

void activateColumnFamily(String name,
                          Object from,
                          Object to)
                   throws UnknownColumnFamily,
                          DatabaseNotReachedException

Activates a given column family (does not activate included persisting elements).

Parameters:

name - name of the column family

from - the minimal (inclusive) value for the activation (a key for a Map column family or a value for a Set column family)

to - the maximal (inclusive) value for the activation (a key for a Map column family or a value for a Set column family)

Throws:

UnknownColumnFamily - in case this column family does not exist

DatabaseNotReachedException

See Also:

getColumnFamily(String)

activateColumnFamilyIfNotAlready

void activateColumnFamilyIfNotAlready(String name)
                               throws UnknownColumnFamily,
                                      DatabaseNotReachedException

Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method). The column family won't be loaded if a previous activation was done, even if a constraint was given by activateColumnFamily(String, Object, Object) or activateColumnFamilyIfNotAlready(String, Object, Object).

Parameters:

name - name of the column family

Throws:

UnknownColumnFamily - in case this column family does not exist

DatabaseNotReachedException

See Also:

getColumnFamily(String), getCachedVersion()

activateColumnFamilyIfNotAlready

void activateColumnFamilyIfNotAlready(String name,
                                      long lastActivationTimeoutMs)
                               throws UnknownColumnFamily,
                                      DatabaseNotReachedException

Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method). The column family won't be loaded if a previous activation was done, even if a constraint was given by activateColumnFamily(String, Object, Object) or activateColumnFamilyIfNotAlready(String, Object, Object).

Parameters:

lastActivationTimeoutMs - the maximum duration (in ms) at which last actual activation was performed. E.g. if last activation happened at 12:00 and method is called at 12:10 while this parameter is set to 3600000 (1 min), activation will happen anyway ; if parameter is set to 40000000, activation will not be performed

name - name of the column family

Throws:

UnknownColumnFamily - in case this column family does not exist

DatabaseNotReachedException

See Also:

getColumnFamily(String), getCachedVersion()

activateColumnFamilyIfNotAlready

void activateColumnFamilyIfNotAlready(String name,
                                      Object from,
                                      Object to)
                               throws UnknownColumnFamily,
                                      DatabaseNotReachedException

Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method). The column family won't be loaded if a previous activation was done, even if a constraint was given by activateColumnFamily(String, Object, Object) or activateColumnFamilyIfNotAlready(String, Object, Object).

Parameters:

name - name of the column family

from - the minimal (inclusive) value for the activation (a key for a Map column family or a value for a Set column family)

to - the maximal (inclusive) value for the activation (a key for a Map column family or a value for a Set column family)

Throws:

UnknownColumnFamily - in case this column family does not exist

DatabaseNotReachedException

See Also:

getColumnFamily(String), getCachedVersion()

activateColumnFamilyIfNotAlready

void activateColumnFamilyIfNotAlready(String name,
                                      long lastActivationTimeoutMs,
                                      Object from,
                                      Object to)
                               throws UnknownColumnFamily,
                                      DatabaseNotReachedException

Activates a given column family (does not activate included persisting elements) in case it was not done before (with any possible activation method). The column family won't be loaded if a previous activation was done, even if a constraint was given by activateColumnFamily(String, Object, Object) or activateColumnFamilyIfNotAlready(String, Object, Object).

Parameters:

lastActivationTimeoutMs - the maximum duration (in ms) at which last actual activation was performed. E.g. if last activation happened at 12:00 and method is called at 12:10 while this parameter is set to 3600000 (1 min), activation will happen anyway ; if parameter is set to 40000000, activation will not be performed

name - name of the column family

from - the minimal (inclusive) value for the activation (a key for a Map column family or a value for a Set column family)

to - the maximal (inclusive) value for the activation (a key for a Map column family or a value for a Set column family)

Throws:

UnknownColumnFamily - in case this column family does not exist

DatabaseNotReachedException

See Also:

getColumnFamily(String), getCachedVersion()

flush

void flush()

Flushes any outgoing request pending on a write-retention store.

equals

boolean equals(Object rhs)

To be equal, two persisting elements must implement the same class and have the same identifier, no matter they have same values for properties and column families.

Overrides:

equals in class Object

See Also:

Object.equals(Object)

hashCode

int hashCode()

The hash code for getIdentifier(). This method make possible to use persisting elements in Hashtables, HashMaps or HashSets.

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

compareTo

int compareTo(PersistingElement rhs)

If instanciated classes are different, class names are compared, in the other case, the result of getIdentifier() are compared. This method make possible to use persisting elements in TreeMaps or TreeSets.

Specified by:

compareTo in interface Comparable<PersistingElement>

See Also:

Comparable.compareTo(Object)

addPersistingElementListener

void addPersistingElementListener(PersistingElementListener listener)

Adds a listener to this persisting element.

removePersistingElementListener

void removePersistingElementListener(PersistingElementListener listener)

Removes a listener to this persisting element.