com.amazon.carbonado
Interface Storage<S extends Storable>

public interface Storage<S extends Storable>

Access for a specific type of Storable from a Repository.

Storage instances are mutable, but they are thread-safe.

Author:

Brian S O'Neill

Method Summary

boolean	addTrigger(Trigger<? super S> trigger) Register a trigger which will be called for overridden methods in the given trigger implementation.
Class<S>	getStorableType() Returns the specific type of Storable managed by this object.
S	prepare() Prepares a new object for loading, inserting, updating, or deleting.
Query<S>	query() Query for all Storable instances in this Storage.
Query<S>	query(Filter<S> filter) Query for Storable instances against an explicitly constructed filter object.
Query<S>	query(String filter) Query for Storable instances against a filter expression.
boolean	removeTrigger(Trigger<? super S> trigger) Remove a trigger which was registered earlier.
void	truncate() Attempts to quickly delete all Storables instances in this Storage.

Method Detail

getStorableType

Class<S> getStorableType()

Returns the specific type of Storable managed by this object.

prepare

S prepare()

Prepares a new object for loading, inserting, updating, or deleting.

Returns:

a new data access object

query

Query<S> query()
                                throws FetchException

Query for all Storable instances in this Storage.

Throws:

FetchException - if storage layer throws an exception

See Also:

query(String)

query

Query<S> query(String filter)
                                throws FetchException

Query for Storable instances against a filter expression. A filter tests if property values match against specific values specified by '?' placeholders. The simplest filter compares just one property, like "ID = ?". Filters can also contain several kinds of relational operators, boolean logic operators, sub-properties, and parentheses. A more complex example might be "income < ? | (name = ? & address.zipCode != ?)".

When querying for a single Storable instance by its primary key, it is generally more efficient to call prepare(), set primary key properties, and then call Storable.load(). For example, consider an object with a primary key consisting only of the property "ID". It can be queried as:

 Storage<UserInfo> users;
 UserInfo user = users.query("ID = ?").with(123456).loadOne();
 

The above code will likely open a Cursor in order to verify that just one object was loaded. Instead, do this:

 Storage<UserInfo> users;
 UserInfo user = users.prepare();
 user.setID(123456);
 user.load();
 

The complete syntax for query filters follows. Note that:

• literals are not allowed
• logical 'and' operator has precedence over 'or'
• logical 'not' operator has precedence over 'and'
• '?' placeholders can only appear after relational operators

 Filter          = OrFilter
 OrFilter        = AndFilter { "|" AndFilter }
 AndFilter       = NotFilter { "&" NotFilter }
 NotFilter       = [ "!" ] EntityFilter
 EntityFilter    = PropertyFilter
                 = ChainedFilter
                 | "(" Filter ")"
 PropertyFilter  = ChainedProperty RelOp "?"
 RelOp           = "=" | "!=" | "<" | ">=" | ">" | "<="
 ChainedFilter   = ChainedProperty "(" [ Filter ] ")"
 ChainedProperty = Identifier
                 | InnerJoin "." ChainedProperty
                 | OuterJoin "." ChainedProperty
 InnerJoin       = Identifier
 OuterJoin       = "(" Identifier ")"
 

Parameters:

filter - query filter expression

Throws:

FetchException - if storage layer throws an exception

IllegalArgumentException - if filter is null

MalformedFilterException - if expression is malformed

UnsupportedOperationException - if given filter is unsupported by repository

query

Query<S> query(Filter<S> filter)
                                throws FetchException

Query for Storable instances against an explicitly constructed filter object.

Parameters:

filter - query filter

Throws:

FetchException - if storage layer throws an exception

IllegalArgumentException - if filter is null

UnsupportedOperationException - if given filter is unsupported by repository

truncate

void truncate()
              throws PersistException

Attempts to quickly delete all Storables instances in this Storage. Support for transactional truncation is not guaranteed.

If this Storage has any registered triggers which act on deletes, all Storables are deleted via query().deleteAll() instead to ensure these triggers get run.

Throws:

PersistException

Since:

1.2

addTrigger

boolean addTrigger(Trigger<? super S> trigger)

Register a trigger which will be called for overridden methods in the given trigger implementation. The newly added trigger is invoked before and after all other triggers. In other words, it is added at the outermost nesting level.

Returns:

true if trigger was added, false if trigger was not added because an equal trigger is already registered

Throws:

IllegalArgumentException - if trigger is null

removeTrigger

boolean removeTrigger(Trigger<? super S> trigger)

Remove a trigger which was registered earlier.

Returns:

true if trigger instance was removed, false if not registered

Throws:

IllegalArgumentException - if trigger is null