com.googlecode.n_orm

Annotation Type Persisting

@Inherited
 @Retention(value=RUNTIME)
 @Target(value=TYPE)
public @interface Persisting

This annotation must be placed on any element with persistence capabilities ; such annotated classes automatically implement and offer services defined by PersistingElement (e.g. activation or storage).

Such defined persisting elements must define one to N non null Key attributes, each of them with a different Key.order(). If a class has N keys, then it must define a key for each order from 1 to N. Keys are essential to compute the identifier (see PersistingElement.getIdentifier()) for persisting elements, which is supposed to be unique for a persisting element (i.e. two elements with the same key values are supposed to represent the same element). Such class can define additional properties. Properties (and keys, which are considered as special properties) are constrained on their type which can be:

• a simple type such as int, String, Double, or other types defined in PersistingElement.PossiblePropertyTypes
• a class annotated with Persisting
• a class which has only Key annotated attributes
• an array of such types (even though its usage is discouraged)

Moreover, persisting classes may define (non final non static non transient) Map or Set elements. Such elements are called column families that can be assigned to null (only). Those column families will be transformed to instances of ColumnFamily (SetColumnFamily for Sets or MapColumnFamily for Maps).

Keys are essential to search persisting elements. Indeed, one can efficiently search for persisting elements between two elements (see PersistingElement.compareTo(PersistingElement)). To perform a search, you will need to state the minimum and maximum value for a given key. If the latter key has Key.order() N, then, to perform the search, exact values for keys with order lower than N have to be supplied. Persisting elements can be searched from the data store using StorageManagement.findElements(). A persisting element whose identifier is known can be created using StorageManagement.getElement(Class, String). In any case, found elements still have to be activated using PersistingElement.activate(String...). So far, key-based search is the only supported approach to search persisting elements. It is also for the more efficient way for most data store (especially distributed hashtable based stores such as column-oriented databases).

A SimpleStore is used to store persisting elements. A persisting element will be stored as a row in the table() corresponding to the class with key (i.e. its qualifier or index) given by PersistingElement.getIdentifier(). Its non-key properties are stored in a column family named "props" (as defined in PropertyManagement.PROPERTY_COLUMNFAMILY_NAME). Keys are also stored there if the annotation defined storeKeys() as true. Column families (Set and Map attributes) are merely stored in column families of the data store.

Other (non static, non transient, non final) attributes are to be stored in the data store (with no additional annotations required).

Moreover, the persisting element has to define either a default constructor (or no constructor at all), or a constructor accepting values fr each key in their defined order (which is supposed to set key values by itself...).

In case of inheritance, the element is stored in the corresponding table() as described above, plus in table()s corresponding to inherited persisting classes. In the tables for ancestors, rows have the same key as in the table for the concrete table, plus the name of the instanciated class (see PersistingElement.getFullIdentifier()). Non-key properties and column families are also stored in tables for superclasses unless storeAlsoInSuperClasses() is set to true.

To be processed, annotated classes must be "exposed" to the aspects defined in this project, you should thus compile your class either with the ajc tool, or use the Maven AspectJ plugin, which requires at runtime a dependency to the AspectJ runtime library in any case.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
FederatedMode	federated States whether this class should target more than one table.
boolean	storeAlsoInSuperClasses States whether values (properties and column families) should also be stored in superclasses.
boolean	storeKeys States whether key values should be stored in the property column family.
String	table The name of the table where should be stored instances.
long	writeRetentionMs The time updates to the data store should be retained before they are sent.

Element Detail

table

public abstract String table

The name of the table where should be stored instances. If let empty (default value), the name of the class is used.

Default:

""

writeRetentionMs

public abstract long writeRetentionMs

The time updates to the data store should be retained before they are sent. In case this number is 0 or below, no retention is applied. This parameter is helpful when a row is quite often updated. Note that activations are not aware of non-sent updates, (e.g. an PersistingElement.activate(String...) will not see new values for at least duration indicated by this parameter).

See Also:

WriteRetentionStore

Default:

0L

storeKeys

public abstract boolean storeKeys

States whether key values should be stored in the property column family. The normal case is that keys are encoded in identifier of the instances.

Default:

false

storeAlsoInSuperClasses

public abstract boolean storeAlsoInSuperClasses

States whether values (properties and column families) should also be stored in superclasses. The normal case is not as information is stored in the table for the instance's class already. This option is helpful if you plan to create queries on superclasses that should also activate properties.

Default:

false

federated

public abstract FederatedMode federated

States whether this class should target more than one table.
When true, class automatically implements PersistingElementOverFederatedTable.
If true, table name is determined on a per-object basis, and the table is the table for the class (see PersistingMixin.getTable(Class) post-fixed with the result of the invocation of PersistingElementOverFederatedTable.getTablePostfix().

Default:

com.googlecode.n_orm.FederatedMode.NONE