Package org.rapidcontext.core.storage

Class Storage

java.lang.Object
org.rapidcontext.core.storage.StorableObject
org.rapidcontext.core.storage.Storage
All Implemented Interfaces:
Comparable<Storage>
Direct Known Subclasses:
DirStorage, MemoryStorage, ZipStorage
public abstract class Storage extends StorableObject implements Comparable<Storage>
The persistent data storage and retrieval class. This base class is extended by storage services to provide actual data lookup and storage.
Version:
1.0

  • Field Details

    • PATH_STORAGEINFO

      public static final Path PATH_STORAGEINFO
      The storage information path. Each storage implementation should provide introspection abilities by returning it's own dictionary when queried for this path.

    • KEY_READWRITE

      public static final String KEY_READWRITE
      The dictionary key for the read-write flag.
      See Also:

    • KEY_MOUNT_PATH

      public static final String KEY_MOUNT_PATH
      The dictionary key for the mount path. The value stored is a path object. If the storage is not mounted, this key is not set or has a null value.
      See Also:

    • KEY_MOUNT_TIME

      public static final String KEY_MOUNT_TIME
      The dictionary key for the mount timestamp. The value stored is a Date object, using the current system time as default.
      See Also:

    • KEY_MOUNT_OVERLAY_PATH

      public static final String KEY_MOUNT_OVERLAY_PATH
      The dictionary key for the mount overlay path. The value stored is a path object indicating if the storage is also mounted as a global overlay. If the storage has not been mounted at all, this key is not set.
      See Also:

    • KEY_MOUNT_OVERLAY_PRIO

      public static final String KEY_MOUNT_OVERLAY_PRIO
      The dictionary key for the mount overlay priority. The value stored is an integer indicating the mount overlay priority, higher numbers corresponding to higher priority. If the storage has not been mounted at all, this key is not set.
      See Also:

    • EXT_PROPERTIES

      public static final String EXT_PROPERTIES
      The file extension for properties data.
      See Also:

    • EXT_JSON

      public static final String EXT_JSON
      The file extension for JSON data.
      See Also:

    • EXT_XML

      public static final String EXT_XML
      The file extension for XML data.
      See Also:

    • EXT_YAML

      public static final String EXT_YAML
      The file extension for YAML data.
      See Also:

    • EXT_ALL

      public static final String[] EXT_ALL
      The list of file extensions supported for data.

  • Constructor Details

    • Storage

      protected Storage(String id, String storageType, boolean readWrite)
      Creates a new storage.
      Parameters:
      id - the storage identifier
      storageType - the storage type name
      readWrite - the read write flag

  • Method Details

    • objectName

      public static String objectName(String name)
      Returns a normalized object name by removing any supported data format file extension (if found).
      Parameters:
      name - the filename or file path to check
      Returns:
      the filename without extension, or the input filename if not recognized

    • objectPath

      public static Path objectPath(Path path)
      Returns a normalized path by removing any supported data format file extension (if found).
      Parameters:
      path - the original path
      Returns:
      the path without trailing extension, or the input path if not recognized

    • serializedPath

      public static Path serializedPath(Path path, String mimeType)
      Returns a serialized path by adding a supported data format file extension.
      Parameters:
      path - the original path
      mimeType - the optional desired MIME type
      Returns:
      the path with a supported file extension, or the input path if an extension was already set

    • serialize

      protected static void serialize(String filename, Object obj, OutputStream os) throws IOException
      Serializes a data object into a data stream.
      Parameters:
      filename - the filename (to choose format)
      obj - the object to write
      os - the output data stream
      Throws:
      IOException - if the serialization failed

    • unserialize

      protected static Object unserialize(String filename, InputStream is) throws IOException
      Unserializes a data stream into a data object.
      Parameters:
      filename - the filename (to choose format)
      is - the input data stream
      Returns:
      the object read, or null if not supported
      Throws:
      IOException - if the unserialization failed

    • compareTo

      public int compareTo(Storage other) throws ClassCastException
      Compares this storage with another.
      Specified by:
      compareTo in interface Comparable<Storage>
      Parameters:
      other - the object to compare with
      Returns:
      a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified one
      Throws:
      ClassCastException - if the object wasn't comparable

    • path

      public Path path()
      Returns the storage mount path.
      Overrides:
      path in class StorableObject
      Returns:
      the storage mount path, or the root path if the storage isn't mounted

    • localPath

      protected Path localPath(Path path)
      Returns a local storage path by removing an optional base storage path. If the specified path does not have the base path prefix, it is returned unmodified.
      Parameters:
      path - the path to adjust
      Returns:
      the local storage path

    • isReadWrite

      public boolean isReadWrite()
      Returns the read-write flag.
      Returns:
      true if the storage is writable, or false otherwise

    • mountTime

      public Date mountTime()
      Returns the storage mount time.
      Returns:
      the storage mount time, or the current system time if not mounted

    • mountOverlayPath

      public Path mountOverlayPath()
      Returns the mount overlay path. This value is set if the storage has been mounted as a global overlay (to the path returned). If the storage has not been mounted at all, null will be returned.
      Returns:
      the storage mount overlay path, or null if no mount overlay is used

    • mountOverlayPrio

      public int mountOverlayPrio()
      Returns the mount overlay priority. Higher numbers correspond to higher priority.
      Returns:
      the mount overlay priority, or -1 if not mounted

    • setMountInfo

      public void setMountInfo(Path path, boolean readWrite, Path overlay, int prio)
      Updates the mount information for this storage. This method will update the mount time to the current timestamp.
      Parameters:
      path - the mount path (or storage root path)
      readWrite - the storage read-write flag
      overlay - the mount overlay path
      prio - the mount overlay priority

    • query

      public Query query(Path base)
      Returns a new storage query for this storage. Supported data file extensions will automatically be hidden by this query.
      Parameters:
      base - the base path (must be an index)
      Returns:
      the storage query

    • lookup

      public abstract Metadata lookup(Path path)
      Searches for an object at the specified location and returns metadata about the object if found. The path may locate either an index or a specific object.
      Parameters:
      path - the storage location
      Returns:
      the metadata for the object, or null if not found

    • load

      public abstract Object load(Path path)
      Loads an object from the specified location. The path may locate either an index or a specific object. In case of an index, the data returned is an index dictionary listing of all objects in it.
      Parameters:
      path - the storage location
      Returns:
      the data read, or null if not found

    • load

      public <T> T load(Path path, Class<T> clazz)
      Loads an object from the specified location. The result must be an instance of a specific class (or subclass).
      Type Parameters:
      T - the type to cast objects to
      Parameters:
      path - the storage location
      clazz - the class required
      Returns:
      the data read, or null if not found or unmatched type

    • store

      public abstract void store(Path path, Object data) throws StorageException
      Stores an object at the specified location. The path must locate a particular object or file, since direct manipulation of indices is not supported. Any previous data at the specified path will be overwritten or removed.
      Parameters:
      path - the storage location
      data - the data to store
      Throws:
      StorageException - if the data couldn't be written

    • remove

      public abstract void remove(Path path) throws StorageException
      Removes an object or an index at the specified location. If the path refers to an index, all contained objects and indices will be removed recursively.
      Parameters:
      path - the storage location
      Throws:
      StorageException - if the data couldn't be removed