Package org.javarosa.core.services.storage

Class WrappingStorageUtility

java.lang.Object
org.javarosa.core.services.storage.WrappingStorageUtility
All Implemented Interfaces:
IStorageUtility, IStorageUtilityIndexed
public class WrappingStorageUtility
extends Object
implements IStorageUtilityIndexed
A wrapper implementation of IStorageUtility that lets you serialize an object with a serialization scheme other than the default scheme provided by the object's readExternal/writeExternal methods. For example, FormInstance contains lots of redundant information about the structure of the instance which doesn't change among saved instances. The extra space used for this redundant info can seriously limit the number of saved forms we can store on a device. We can use this utility to serialize FormInstances in a different way that excludes this redundant info (meaning we have to take the more complicated step of restoring it from elsewhere during deserialization), with the benefit of much smaller record sizes. The alternate scheme is provided via a wrapper object, which accepts the base object and whose readExternal/writeExternal methods implement the new scheme. All methods pass through to an underlying StorageUtility; you may get warnings about type mismatches
Author:
Drew Roos

  • Constructor Details

  • Method Details

    • read

      public Externalizable read​(int id)
      Description copied from interface: IStorageUtility
      Read and return the record corresponding to 'id'.
      Specified by:
      read in interface IStorageUtility
      Parameters:
      id - id of the object
      Returns:
      object for 'id'. null if no object is stored under that ID

    • write

      public void write​(Persistable p) throws StorageFullException
      Description copied from interface: IStorageUtility
      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
      Specified by:
      write in interface IStorageUtility
      Parameters:
      p - object to store
      Throws:
      StorageFullException - if there is not enough room to store the object

    • add

      public int add​(Externalizable e) throws StorageFullException
      Description copied from interface: IStorageUtility
      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.
      Specified by:
      add in interface IStorageUtility
      Parameters:
      e - object to add
      Returns:
      record ID for newly added object
      Throws:
      StorageFullException - if not enough space available

    • update

      public void update​(int id, Externalizable e) throws StorageFullException
      Description copied from interface: IStorageUtility
      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.
      Specified by:
      update in interface IStorageUtility
      Parameters:
      id - ID of record to update
      e - updated object
      Throws:
      StorageFullException - if not enough space available to update

    • iterate

      public IStorageIterator iterate()
      Description copied from interface: IStorageUtility
      Return an iterator to iterate through all records in this store
      Specified by:
      iterate in interface IStorageUtility
      Returns:
      record iterator

    • readBytes

      public byte[] readBytes​(int id)
      Description copied from interface: IStorageUtility
      Read and return the raw bytes for the record corresponding to 'id'.
      Specified by:
      readBytes in interface IStorageUtility
      Parameters:
      id - id of the object
      Returns:
      raw bytes for the record. null if no record is stored under that ID

    • remove

      public void remove​(int id)
      Description copied from interface: IStorageUtility
      Remove record with the given ID from the store.
      Specified by:
      remove in interface IStorageUtility
      Parameters:
      id - ID of record to remove

    • remove

      public void remove​(Persistable p)
      Description copied from interface: IStorageUtility
      Remove object from the store
      Specified by:
      remove in interface IStorageUtility
      Parameters:
      p - object to remove

    • removeAll

      public void removeAll()
      Specified by:
      removeAll in interface IStorageUtility

    • removeAll

      public List<Integer> removeAll​(EntityFilter ef)
      Specified by:
      removeAll in interface IStorageUtility

    • exists

      public boolean exists​(int id)
      Description copied from interface: IStorageUtility
      Return whether a record exists in the store
      Specified by:
      exists in interface IStorageUtility
      Parameters:
      id - record ID
      Returns:
      true if a record exists for that ID in the store

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: IStorageUtility
      Return whether the store is empty
      Specified by:
      isEmpty in interface IStorageUtility
      Returns:
      true if there are no records in the store

    • getNumRecords

      public int getNumRecords()
      Description copied from interface: IStorageUtility
      Return the number of records in the store
      Specified by:
      getNumRecords in interface IStorageUtility
      Returns:
      number of records

    • getRecordSize

      public int getRecordSize​(int id)
      Description copied from interface: IStorageUtility
      Get the size of a record
      Specified by:
      getRecordSize in interface IStorageUtility
      Parameters:
      id - record ID
      Returns:
      size of that record, in bytes

    • getTotalSize

      public int getTotalSize()
      Description copied from interface: IStorageUtility
      Return total size of device storage consumed by this StorageUtility
      Specified by:
      getTotalSize in interface IStorageUtility
      Returns:
      total size (bytes)

    • close

      public void close()
      Description copied from interface: IStorageUtility
      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.).
      Specified by:
      close in interface IStorageUtility

    • destroy

      public void destroy()
      Description copied from interface: IStorageUtility
      Delete the storage utility itself, along with all stored records and meta-data
      Specified by:
      destroy in interface IStorageUtility

    • repack

      public void repack()
      Description copied from interface: IStorageUtility
      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)
      Specified by:
      repack in interface IStorageUtility

    • repair

      public void repair()
      Description copied from interface: IStorageUtility
      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
      Specified by:
      repair in interface IStorageUtility

    • getAccessLock

      public Object getAccessLock()
      Description copied from interface: IStorageUtility
      Fetch the object that acts as the synchronization lock for this StorageUtility
      Specified by:
      getAccessLock in interface IStorageUtility
      Returns:
      lock object

    • getIDsForValue

      public List<Integer> getIDsForValue​(String fieldName, Object value)
      Description copied from interface: IStorageUtilityIndexed
      Retrieves a List of IDs of Externalizable objects in storage for which the field specified contains the value specified.
      Specified by:
      getIDsForValue in interface IStorageUtilityIndexed
      Parameters:
      fieldName - The name of a field which should be evaluated
      value - The value which should be contained by the field specified
      Returns:
      A List of Integers such that retrieving the Externalizable object with any of those integer IDs will result in an object for which the field specified is equal to the value provided.

    • getRecordForValue

      public Externalizable getRecordForValue​(String fieldName, Object value) throws NoSuchElementException, InvalidIndexException
      Description copied from interface: IStorageUtilityIndexed
      Retrieves a Externalizable object from the storage which is reference by the unique index fieldName.
      Specified by:
      getRecordForValue in interface IStorageUtilityIndexed
      Parameters:
      fieldName - The name of the index field which will be evaluated
      value - The value which should be set in the index specified by fieldName for the returned object.
      Returns:
      An Externalizable object e, such that e.getMetaData(fieldName).equals(value);
      Throws:
      NoSuchElementException - If no objects reside in storage for which the return condition can be successful.
      InvalidIndexException - If the field used is an invalid index, because more than one field in the Storage contains the value of the index requested.

    • setReadOnly

      public void setReadOnly()
      Specified by:
      setReadOnly in interface IStorageUtility

    • registerIndex

      public void registerIndex​(String filterIndex)
      Description copied from interface: IStorageUtilityIndexed
      Optional. Register a new index for this storage which may optionally be able for indexed operations going forward. This will likely take a substantial amount of time for larger storage utilities.
      Specified by:
      registerIndex in interface IStorageUtilityIndexed