IStorageUtility (javarosa 4.3.0 API)

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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and 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 Detail
  - 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()
```

Interface IStorageUtility<E extends Externalizable>

Method Summary

Method Detail

read

readBytes

write

add

update

remove

remove

removeAll

removeAll

getNumRecords

isEmpty

exists

getTotalSize

getRecordSize

iterate

close

destroy

repack

repair

getAccessLock

setReadOnly