org.rapidcontext.core.storage

Class StorableObject

java.lang.Object

org.rapidcontext.core.storage.StorableObject

Direct Known Subclasses:

Connection, Environment, Index, Metadata, Plugin, Role, Session, Storage, Type, User, WebService

public class StorableObject
extends java.lang.Object

The base class for all storable Java objects. This class provides a number of basic services required for managing objects in the storage subsystem:

• Object Type -- The object type identifies the kind of object, e.g. "index", "file", "plugin", etc. By registering a Java class corresponding to an object type, the instance creation is handled automatically when a new object is loaded from storage.
• Object Id -- The object identifier is used to locate the object in a storage. The full object storage path is normally formed as "<type>/<id>". Note that the object id may contain additional "/" characters.
• Serialization -- A data dictionary instance is encapsulated to enable simple and efficient serialization and unserialization of object instances. It is recommended to store all persistent data in this dictionary, although both serialization and unserialization can be overridden.
• Life-cycle Handling -- Object instances are initialized, destroyed and cached automatically by the root storage. Whenever an instance reports being inactive, it is eligible for automatic removal (destruction) from the cache.

Version:

1.0

Author:

Per Cederberg

Field Summary

Fields

Modifier and Type	Field and Description
protected Dict	dict The dictionary containing the serializable data for this object.
static java.lang.String	KEY_CLASSNAME The dictionary key for the Java class name.
static java.lang.String	KEY_ID The dictionary key for the object identifier.
static java.lang.String	KEY_TYPE The dictionary key for the object type.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StorableObject(java.lang.String id, java.lang.String type) Creates a new object.
protected	StorableObject(java.lang.String id, java.lang.String type, Dict dict) Creates a new object from a serialized representation.

Method Summary

Modifier and Type	Method and Description
protected void	activate() Activates this object.
protected void	destroy() Destroys this object.
java.lang.String	id() Returns the object identifier.
protected void	init() Initializes this object after loading it from a storage.
protected boolean	isActive() Checks if this object is in active use.
protected boolean	isModified() Checks if this object has been modified since initialized from storage.
protected void	passivate() Attempts to deactivate this object.
Path	path() Returns the (recommended) object storage path.
Dict	serialize() Returns a serialized representation of this object.
java.lang.String	toString() Returns a string representation of this object.
java.lang.String	type() Returns the object type name.

Methods inherited from class java.lang.Object

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

Field Detail

KEY_ID

public static final java.lang.String KEY_ID

The dictionary key for the object identifier. The value stored is a string and is used to form the object storage path.

See Also:

Constant Field Values

KEY_TYPE

public static final java.lang.String KEY_TYPE

The dictionary key for the object type. The value stored is a string and is used as the prefix when forming the object storage path.

See Also:

Constant Field Values

KEY_CLASSNAME

public static final java.lang.String KEY_CLASSNAME

The dictionary key for the Java class name. The value stored is a string with the fully qualified Java class name for initializing the object from storage. The class is used instead of the default type initializer, but the type id must still be specified.

See Also:

Constant Field Values

dict

protected Dict dict

The dictionary containing the serializable data for this object.

Constructor Detail

StorableObject

protected StorableObject(java.lang.String id,
                         java.lang.String type)

Creates a new object. This is the default constructor for creating storable object instances.

Parameters:

id - the object identifier

type - the type name

StorableObject

protected StorableObject(java.lang.String id,
                         java.lang.String type,
                         Dict dict)

Creates a new object from a serialized representation. This constructor should normally only be used for unserialization. The key-value pairs from the specified dictionary will be copied (shallow copy) into a new dictionary.

Note: This constructor signature is used for automatic object creation (unserialization). Subclasses using this feature MUST implement a public constructor with this exact signature.

Parameters:

id - the object identifier

type - the object type name

dict - the serialized representation

See Also:

init()

Method Detail

toString

public java.lang.String toString()

Returns a string representation of this object.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this object

isActive

protected boolean isActive()

Checks if this object is in active use. This method should return true if the object is in use, was used recently, or is likely to be requested again shortly. The outcome is used to remove non-active object instances from the storage cache. By default, this method always returns true.

Returns:

true if the object is active, or false otherwise

isModified

protected boolean isModified()

Checks if this object has been modified since initialized from storage. This method is used to allow "dirty" objects to be written back to persistent storage before being evicted from the in-memory cache. By default this method always returns false.

Returns:

true if the object has been modified, or false otherwise

id

public java.lang.String id()

Returns the object identifier.

Returns:

the object identifier

type

public java.lang.String type()

Returns the object type name.

Returns:

the object type name

path

public Path path()

Returns the (recommended) object storage path. The storage path is created by concatenating the object type and id.

Returns:

the object storage path

init

protected void init()
             throws StorageException

Initializes this object after loading it from a storage. Any object initialization that may fail or that causes the object to interact with any other part of the system (or external systems) should be implemented here.

This method is guaranteed to be called before the object is returned from the storage. If this method throws an exception, the destroy() method will NOT be called.

Throws:

StorageException - if the initialization failed

destroy

protected void destroy()
                throws StorageException

Destroys this object. This method is used to free any resources used when this object is no longer used. This method is called when an object is removed from the in-memory storage (object cache).

Note: The object destruction cannot be halted by throwing an exception. The exception message will only be logged by the storage.

Throws:

StorageException - if the destruction failed

activate

protected void activate()

Activates this object. This method is called whenever the object instance is returned from storage and may be called by several threads in parallel. The default implementation does nothing.

passivate

protected void passivate()

Attempts to deactivate this object. This method is called by a background task, roughly every 30 seconds for all object instances in the storage cache. It may be called earlier on the first invocation, since all objects share a common timer. The default implementation does nothing.

serialize

public Dict serialize()

Returns a serialized representation of this object. Used when persisting to permanent storage or when accessing the object from outside pure Java. By default this method will return the contained dictionary.

Returns:

the serialized representation of this object