Package org.javarosa.core.services.storage

Interface IStorageUtility<E extends Externalizable>

All Known Subinterfaces:
IStorageUtilityIndexed<E>
All Known Implementing Classes:
DummyIndexedStorageUtility, WrappingStorageUtility
public interface IStorageUtility<E extends Externalizable>
IStorageUtility Implementations of this interface provide persistent records-based storage in which records are stored and retrieved using record IDs. IStorageUtility can be used in two flavors: you manage the IDs, or the utility manages the IDs: If you manage the IDs, the objects you are storing must implement Persistable, which provides the ID from the object itself. You then use the functions read(), write(), and remove() when dealing with storage. If the utility manages the IDs, your objects need only implement Externalizable. You use the functions read(), add(), update(), and remove(). add() will return a new ID for the record, which you then explicitly provide to all subsequent calls to update(). These two schemes should not be mixed within the same StorageUtility.

  • Method Summary

    Modifier and Type Method Description
    int add​(E e)
    Add a new record to the store.
    void close()
    Close all resources associated with this StorageUtility.
    void destroy()
    Delete the storage utility itself, along with all stored records and meta-data
    boolean exists​(int id)
    Return whether a record exists in the store
    Object getAccessLock()
    Fetch the object that acts as the synchronization lock for this StorageUtility
    int getNumRecords()
    Return the number of records in the store
    int getRecordSize​(int id)
    Get the size of a record
    int getTotalSize()
    Return total size of device storage consumed by this StorageUtility
    boolean isEmpty()
    Return whether the store is empty
    IStorageIterator<E> iterate()
    Return an iterator to iterate through all records in this store
    E read​(int id)
    Read and return the record corresponding to 'id'.
    byte[] readBytes​(int id)
    Read and return the raw bytes for the record corresponding to 'id'.
    void remove​(int id)
    Remove record with the given ID from the store.
    void remove​(Persistable p)
    Remove object from the store
    void removeAll()  
    List<Integer> removeAll​(EntityFilter ef)  
    void repack()
    Perform any clean-up/consolidation of the StorageUtility's underlying datastructures that is too expensive to do during normal usage (e.g., if all the records are scattered among 10 half-empty RMSes, repack them into 5 full RMSes)
    void repair()
    If the StorageUtility has been left in a corrupt/inconsistent state, restore it to a non-corrupt state, even if it results in data loss.
    void setReadOnly()  
    void update​(int id, E e)
    Update a record in the store.
    void write​(Persistable p)
    Write an object to the store.

  • Method Details

    • read

      E read​(int id)
      Read and return the record corresponding to 'id'.
      Parameters:
      id - id of the object
      Returns:
      object for 'id'. null if no object is stored under that ID

    • readBytes

      byte[] readBytes​(int id)
      Read and return the raw bytes for the record corresponding to 'id'.
      Parameters:
      id - id of the object
      Returns:
      raw bytes for the record. null if no record is stored under that ID

    • write

      void write​(Persistable p) throws StorageFullException
      Write an object to the store. Will either add a new record, or update the existing record (if one exists) for the object's ID. This function should never be used in conjunction with add() and update() within the same StorageUtility
      Parameters:
      p - object to store
      Throws:
      StorageFullException - if there is not enough room to store the object

    • add

      int add​(E e) throws StorageFullException
      Add a new record to the store. This function always adds a new record; it never updates an existing record. The record ID under which this record is added is allocated by the StorageUtility. If this StorageUtility stores Persistables, you should almost certainly use write() instead.
      Parameters:
      e - object to add
      Returns:
      record ID for newly added object
      Throws:
      StorageFullException - if not enough space available

    • update

      void update​(int id, E e) throws StorageFullException
      Update a record in the store. The record must have previously been added to the store using add(). If this StorageUtility stores Persistables, you should almost certainly use write() instead.
      Parameters:
      id - ID of record to update
      e - updated object
      Throws:
      StorageFullException - if not enough space available to update
      IllegalArgumentException - if no record exists for ID

    • remove

      void remove​(int id)
      Remove record with the given ID from the store.
      Parameters:
      id - ID of record to remove
      Throws:
      IllegalArgumentException - if no record with that ID exists

    • remove

      void remove​(Persistable p)
      Remove object from the store
      Parameters:
      p - object to remove
      Throws:
      IllegalArgumentException - if object is not in the store

    • removeAll

      void removeAll()

    • removeAll

      List<Integer> removeAll​(EntityFilter ef)

    • getNumRecords

      int getNumRecords()
      Return the number of records in the store
      Returns:
      number of records

    • isEmpty

      boolean isEmpty()
      Return whether the store is empty
      Returns:
      true if there are no records in the store

    • exists

      boolean exists​(int id)
      Return whether a record exists in the store
      Parameters:
      id - record ID
      Returns:
      true if a record exists for that ID in the store

    • getTotalSize

      int getTotalSize()
      Return total size of device storage consumed by this StorageUtility
      Returns:
      total size (bytes)

    • getRecordSize

      int getRecordSize​(int id)
      Get the size of a record
      Parameters:
      id - record ID
      Returns:
      size of that record, in bytes
      Throws:
      IllegalArgumentException - if no record exists for that ID

    • iterate

      IStorageIterator<E> iterate()
      Return an iterator to iterate through all records in this store
      Returns:
      record iterator

    • close

      void close()
      Close all resources associated with this StorageUtility. Any attempt to use this StorageUtility after this call will result in error. Though not strictly necessary, it is a good idea to call this when you are done with the StorageUtility, as closing may trigger clean-up in the underlying device storage (reclaiming unused space, etc.).

    • destroy

      void destroy()
      Delete the storage utility itself, along with all stored records and meta-data

    • repack

      void repack()
      Perform any clean-up/consolidation of the StorageUtility's underlying datastructures that is too expensive to do during normal usage (e.g., if all the records are scattered among 10 half-empty RMSes, repack them into 5 full RMSes)

    • repair

      void repair()
      If the StorageUtility has been left in a corrupt/inconsistent state, restore it to a non-corrupt state, even if it results in data loss. If the integrity is intact, do nothing

    • getAccessLock

      Object getAccessLock()
      Fetch the object that acts as the synchronization lock for this StorageUtility
      Returns:
      lock object

    • setReadOnly

      void setReadOnly()