com.sag.osami.api.context
Interface IContextStorage

All Known Subinterfaces:
ISerializedContextStorage
All Known Implementing Classes:
AndroidStorage, JDBCStorage, NullStorage, SerializedContextStorage

public interface IContextStorage

This interface provides low-level methods for storing, loading, deleting and querying context events in the ContextStore. No method (in particular store(ContextEvent)) will ever invoke any IContextHandler logic, nor will it register new context types in the ContextStore etc. All methods strictly handle storage concerns and nothing further.

Important: This interface is intended for public use. It is NOT the actual interface which is used internally for storage management. If you plan to implement a custom storage management class, see ISerializedContextStorage.

OSGi notice: In OSGi environments, the storage implementation should be registered as a service providing this interface. When no custom storage back-end is provided, the shipped one is registered accordingly (see db.DerbyStorage).


Method Summary
 void delete(java.util.List<java.lang.Long> contextIds)
          Deletes several context events with given IDs.
 void delete(java.lang.Long contextId)
          Deletes a context event with given ID.
 void delete(java.lang.String query, java.lang.Object... params)
          Deletes several context events defined by the query.
 ContextEvent[] load(java.util.List<java.lang.Long> contextIds)
          Loads several context events with the given IDs.
 ContextEvent load(java.lang.Long contextId)
          Loads a context event with the given ID.
 java.lang.Iterable<ContextEvent> loadLazy(java.util.List<java.lang.Long> contextIds)
          Lazy variant of load(List), i.e. it loads one ContextEvent at a time during iteration.
 ContextEvent[] query(java.lang.String query, java.lang.Object... params)
          Queries several context events.
 java.lang.Iterable<ContextEvent> queryLazy(java.lang.String query, java.lang.Object... params)
          Lazy variant of query(String, Object...), i.e. it loads one ContextEvent at a time during iteration.
 void store(ContextEvent context)
          Stores a context event object persistently.
 

Method Detail

load

ContextEvent load(java.lang.Long contextId)
Loads a context event with the given ID.

Parameters:
contextId - ID of the context event
Returns:
loaded context event (or null, if there is no context event with given ID)

load

ContextEvent[] load(java.util.List<java.lang.Long> contextIds)
Loads several context events with the given IDs. The order within the result is unspecified.

Parameters:
contextIds - IDs of the context events.
Returns:
loaded context events (or a zero-length array, if there are no context events with given IDs)

loadLazy

java.lang.Iterable<ContextEvent> loadLazy(java.util.List<java.lang.Long> contextIds)
                                          throws java.lang.UnsupportedOperationException
Lazy variant of load(List), i.e. it loads one ContextEvent at a time during iteration. This operation is optional.

Parameters:
contextIds - IDs of the context events.
Throws:
java.lang.UnsupportedOperationException - if the underlying storage implementation does not support lazy querying
See Also:
load(List)

query

ContextEvent[] query(java.lang.String query,
                     java.lang.Object... params)
Queries several context events.

Parameters:
query - Its language/format depends on the actual storage management class.
params - Should be used for parameter binding à la JDBC: query("SELECT * FROM contextstore WHERE type = ? AND timestamp >= ?", "someType", someDate.getTime());
Returns:
queried context events (or a zero-length array, if there are no according context events)

queryLazy

java.lang.Iterable<ContextEvent> queryLazy(java.lang.String query,
                                           java.lang.Object... params)
                                           throws java.lang.UnsupportedOperationException
Lazy variant of query(String, Object...), i.e. it loads one ContextEvent at a time during iteration. This operation is optional.

Parameters:
query - The context event query.
params - Parameters for the query.
Throws:
java.lang.UnsupportedOperationException - if the underlying storage implementation does not support lazy querying
See Also:
query(String, Object...)

store

void store(ContextEvent context)
Stores a context event object persistently.

Parameters:
context - context event object to be stored.

delete

void delete(java.lang.Long contextId)
Deletes a context event with given ID.

Parameters:
contextId - ID of context event to be deleted.

delete

void delete(java.util.List<java.lang.Long> contextIds)
Deletes several context events with given IDs.

Parameters:
contextIds - IDs of context events to be deleted.

delete

void delete(java.lang.String query,
            java.lang.Object... params)
Deletes several context events defined by the query.

Parameters:
query - Defines the context events to be deleted.
params - Parameters for the query.
See Also:
query(String, Object...)