Storage (Carbonado 1.2.3 API)

+
+
+
```
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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Methods
Modifier and Type	Method and Description
`boolean`	`addTrigger(Trigger<? super S> trigger)` + Register a trigger which will be called for overridden methods in the given + trigger implementation. +
`java.lang.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(java.lang.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
    +
```
java.lang.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(java.lang.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
    +
    java.lang.IllegalArgumentException - if filter is null
    +
    MalformedFilterException - if expression is malformed
    +
    java.lang.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
    +
    java.lang.IllegalArgumentException - if filter is null
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.IllegalArgumentException - if trigger is null
    +
  +
+

Interface Storage<S extends Storable>

Method Summary

Method Detail

getStorableType

prepare

query

query

query

truncate

addTrigger

removeTrigger