com.sag.osami.contextstore.storage
Interface ISerializedContextStorage

All Superinterfaces:
IContextStorage
All Known Implementing Classes:
AndroidStorage, JDBCStorage, NullStorage, SerializedContextStorage

public interface ISerializedContextStorage
extends IContextStorage

This interface is used by ContextStore for all storage-related logic. Any actual ContextStore storage back-end has to implement this interface.

The methods are basically the same as in IContextStorage, but include (de)serialization flags. Payload serialization obviously plays a role in storage-related program logic. On the other hand, serialization details should not be exposed to the regular ContextStore user (i.e. should not be part of the public API).

However, it wouldn't suffice to encapsulate and hide serialization completely within the storage back-end by simply using IContextStorage as the internal interface (which does not expose any serialization flags etc.) in the ContextStore: in internal ContextStore logic, on different occasions it is necessary/convenient to obtain IContextEvents with either already deserialized or still serialized payload data; similarly, on different occasions it is necessary/convenient to store IContextEvents with either already serialized or still deserialized payload data.

Hence, a storage back-end has to account for the two possible forms of payload data and handle it accordingly. For this, it must have access to the ISerializationHandler, which is granted by setSerializer(ISerializationHandler).

As the ContextStore is responsible for assigning unique IDs to context events, it must be able to retrieve the last given ID during its initialization -- this capability also is to be provided by the storage back-end.

See Also:
SerializedContextStorage

Method Summary
 ContextEvent[] load(boolean deserialize, java.util.List<java.lang.Long> contextIds)
          Loads several context events with the given IDs.
 ContextEvent load(boolean deserialize, java.lang.Long contextId)
          Loads a context event with the given ID.
 java.lang.Iterable<ContextEvent> loadLazy(boolean deserialize, java.util.List<java.lang.Long> contextIds)
          Lazy variant of load(boolean, List), i.e. it loads one ContextEvent at a time during iteration.
 ContextEvent[] query(boolean deserialize, java.lang.String query, java.lang.Object... params)
          Queries several context events.
 java.lang.Iterable<ContextEvent> queryLazy(boolean deserialize, java.lang.String query, java.lang.Object... params)
          Lazy variant of query(boolean, String, Object...), i.e. it loads one ContextEvent at a time during iteration.
 java.lang.Long retrieveLastID()
          ContextStore uses the result of this method as the offset for its auto-incremented context event IDs.
 void setSerializer(ISerializationHandler serializer)
          Grants access to the payload data serialization handler.
 void store(boolean serialize, ContextEvent context)
          Stores a context event object persistently.
 
Methods inherited from interface com.sag.osami.api.context.IContextStorage
delete, delete, delete, load, load, loadLazy, query, queryLazy, store
 

Method Detail

load

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

Parameters:
deserialize - whether the payload data should remain serialized or should be deserialized
contextId - ID of the context event
Returns:
loaded context event (or null, if there is no context event with given ID)

load

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

Parameters:
deserialize - whether the payload data should remain serialized or should be deserialized
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(boolean deserialize,
                                          java.util.List<java.lang.Long> contextIds)
                                          throws java.lang.UnsupportedOperationException
Lazy variant of load(boolean, List), i.e. it loads one ContextEvent at a time during iteration. This operation is optional.

Throws:
java.lang.UnsupportedOperationException - if the underlying storage implementation does not support lazy querying
See Also:
load(boolean, List)

query

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

Parameters:
deserialize - whether the payload data should remain serialized or should be deserialized
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(boolean deserialize,
                                           java.lang.String query,
                                           java.lang.Object... params)
                                           throws java.lang.UnsupportedOperationException
Lazy variant of query(boolean, String, Object...), i.e. it loads one ContextEvent at a time during iteration. This operation is optional.

Throws:
java.lang.UnsupportedOperationException - if the underlying storage implementation does not support lazy querying
See Also:
query(boolean, String, Object...)

store

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

Parameters:
serialize - whether the payload data should be serialized or not (because it is already serialized)
context - context event object to be stored

setSerializer

void setSerializer(ISerializationHandler serializer)
Grants access to the payload data serialization handler.

Parameters:
serializer - payload data serialization handler

retrieveLastID

java.lang.Long retrieveLastID()
ContextStore uses the result of this method as the offset for its auto-incremented context event IDs. This method is used only during the initialization of the ContextStore, it doesn't have to return the current last given ID during the whole lifetime.

Returns:
the so-far highest already assigned ID of a persisted context event