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, Vault, WebService
public class StorableObject extends 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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Dict
    dict
    The dictionary containing the serializable data for this object.
    static final String
    KEY_ACTIVATED_TIME
    The dictionary key for the most recent object activation time.
    static final String
    KEY_CLASSNAME
    The dictionary key for the Java class name.
    static final String
    KEY_ID
    The dictionary key for the object identifier.
    static final String
    KEY_TYPE
    The dictionary key for the object type.
    static final String
    PREFIX_COMPUTED
    The prefix for computed dictionary keys.
    static final String
    PREFIX_HIDDEN
    The prefix for hidden dictionary keys.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    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 Type
    Method
    Description
    protected void
    activate()
    Activates this object.
    protected Date
    activatedTime()
    Returns the timestamp of the latest object activation.
    protected void
    destroy()
    Destroys this object.
    protected String
    dictKey(String key)
    Finds the dictionary key to use.
    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.
    static Object
    sterilize(Object obj, boolean skipHidden, boolean skipComputed, boolean limitedTypes)
    Serializes an object and recursively removes hidden and computed keys.
    String
    toString()
    Returns a string representation of this object.
    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 Details

    • KEY_ID

      public static final 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:

    • KEY_TYPE

      public static final 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:

    • KEY_CLASSNAME

      public static final 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:

    • KEY_ACTIVATED_TIME

      public static final String 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

      public static final String 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

      public static final String 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

      protected Dict dict
      The dictionary containing the serializable data for this object.

  • Constructor Details

    • StorableObject

      protected StorableObject(String id, 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(String id, 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:

  • 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 sterilize
      skipHidden - filter out hidden key-value pairs
      skipComputed - filter out computed key-value pairs
      limitedTypes - limit allowed object value types
      Returns:
      the sterilized object

    • toString

      public String toString()
      Returns a string representation of this object.
      Overrides:
      toString in class 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 String id()
      Returns the object identifier.
      Returns:
      the object identifier

    • type

      public 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

    • activatedTime

      protected Date 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

    • dictKey

      protected String dictKey(String key)
      Finds the dictionary key to use. Tests for the existence of either computed or hidden prefixes to the key. If none were found, the input key is returned unmodified.
      Parameters:
      key - the dictionary key name
      Returns:
      the dictionary key to use

    • 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. Returns a shallow copy of the contained dictionary.
      Returns:
      the serialized representation of this object