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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	WrappingStorageUtility.SerializationWrapper Defines an alternate serialization scheme.

Constructor Summary

Constructors

Constructor and Description
WrappingStorageUtility(String name, WrappingStorageUtility.SerializationWrapper wrapper, IStorageFactory storageFactory) Create a new wrapping StorageUtility

Method Summary

Modifier and Type	Method and Description
int	add(Externalizable 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
List<Integer>	getIDsForValue(String fieldName, Object value) Retrieves a List of IDs of Externalizable objects in storage for which the field specified contains the value specified.
int	getNumRecords() Return the number of records in the store
Externalizable	getRecordForValue(String fieldName, Object value) Retrieves a Externalizable object from the storage which is reference by the unique index fieldName.
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	iterate() Return an iterator to iterate through all records in this store
Externalizable	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	registerIndex(String filterIndex) Optional.
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, Externalizable e) Update a record in the store.
void	write(Persistable p) Write an object to the store.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WrappingStorageUtility

public WrappingStorageUtility(String name,
                              WrappingStorageUtility.SerializationWrapper wrapper,
                              IStorageFactory storageFactory)

Create a new wrapping StorageUtility

Parameters:

name - unique name for underlying StorageUtility

wrapper - serialization wrapper

storageFactory - factory to create underlying StorageUtility

Method Detail

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