Package org.rapidcontext.core.storage
Class StorableObject
java.lang.Object
org.rapidcontext.core.storage.StorableObject
- Direct Known Subclasses:
Connection
,Environment
,Metadata
,Metrics
,Plugin
,Procedure
,Role
,Session
,Storage
,Type
,User
,WebService
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
-
Field Summary
Modifier and TypeFieldDescriptionprotected Dict
The dictionary containing the serializable data for this object.static final String
The dictionary key for the most recent object activation time.static final String
The dictionary key for the Java class name.static final String
The dictionary key for the object identifier.static final String
The dictionary key for the object type.static final String
The prefix for computed dictionary keys.static final String
The prefix for hidden dictionary keys. -
Constructor Summary
ModifierConstructorDescriptionprotected
StorableObject
(String id, String type) Creates a new object.protected
StorableObject
(String id, String type, Dict dict) Creates a new object from a serialized representation. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
activate()
Activates this object.protected Date
Returns the timestamp of the latest object activation.protected void
destroy()
Destroys this object.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
Checks if this object has been modified since initialized from storage.protected void
Attempts to deactivate this object.path()
Returns the (recommended) object storage path.Returns a serialized representation of this object.static Object
Serializes an object and recursively removes hidden and computed keys.toString()
Returns a string representation of this object.type()
Returns the object type name.
-
Field Details
-
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:
-
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:
-
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:
-
KEY_ACTIVATED_TIME
The dictionary key for the most recent object activation time. The value is stored as a date object. Note that this is always stored as a computed property, so it will not be written to storage.- See Also:
-
PREFIX_HIDDEN
The prefix for hidden dictionary keys. These will not be returned by API calls, but will be written to storage.- See Also:
-
PREFIX_COMPUTED
The prefix for computed dictionary keys. These will not be written to persistent storage, but may be returned from API calls.- See Also:
-
dict
The dictionary containing the serializable data for this object.
-
-
Constructor Details
-
StorableObject
Creates a new object. This is the default constructor for creating storable object instances.- Parameters:
id
- the object identifiertype
- the type name
-
StorableObject
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 identifiertype
- the object type namedict
- the serialized representation- See Also:
-
-
Method Details
-
sterilize
public static Object sterilize(Object obj, boolean skipHidden, boolean skipComputed, boolean limitedTypes) Serializes an object and recursively removes hidden and computed keys. This is typically performed before returning a storable object via API or when writing to storage.- Parameters:
obj
- the object to sterilizeskipHidden
- filter out hidden key-value pairsskipComputed
- filter out computed key-value pairslimitedTypes
- limit allowed object value types- Returns:
- the sterilized object
-
toString
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
Returns the object identifier.- Returns:
- the object identifier
-
type
Returns the object type name.- Returns:
- the object type name
-
path
Returns the (recommended) object storage path. The storage path is created by concatenating the object type and id.- Returns:
- the object storage path
-
activatedTime
Returns the timestamp of the latest object activation. This is updated each time the object is fetched from storage.- Returns:
- the timestamp of the latest object activation, or null if not activated
-
init
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
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
Returns a serialized representation of this object. Used when persisting to permanent storage or when accessing the object from outside pure Java. Returns a shallow copy of the contained dictionary.- Returns:
- the serialized representation of this object
-