com.sag.osami.contextstore
Class ContextStore

java.lang.Object
  extended by com.sag.osami.contextstore.ContextStore
All Implemented Interfaces:
IContextQuery, IContextStore, ISerializedContextReceiver

public final class ContextStore
extends java.lang.Object
implements ISerializedContextReceiver, IContextQuery

Being the actual implementation of the ContextStore pattern, this class manages IContextHandlers and dispatches and persists ContextEvents.

It implements all generic functionality, in particular handler-specific functionality as (de)registering context handlers and passing over context events to the according (interested) handlers.

It delegates all storage-related methods as loading, storing and querying ContextEvents to an implementation of a ISerializedContextStorage.

It is noteworthy that this version of the ContextStore uses worker threads for the processing of the registered IContextHandlers. Thus the semantics of context event creation changed crucially: newContextEvent(String, String, Object, Date) etc. are no longer synchronous, i.e. it cannot be assumed that the newly created event is already handled by all interested handlers after newContextEvent was executed.

By processing the context handlers concurrently, the overall speed is improved, especially on modern multi-core CPU architectures (in fact, the number of handler worker threads corresponds to the number of CPU cores). Methods like registerHandler(IContextHandler) etc. are thread-safe.

For creating a ContextStore instance conveniently, the builder class ContextStoreBuilder can be used.

All internally used components such as the serialization handler and the storage implementation are used strictly through well-defined interfaces and therefore can be replaced with custom implementations. See ContextStoreBuilder and OsgiContextStoreActivator for an overview how to replace the default components.

See Also:
ISerializedContextStorage, IContextHandler, ContextStoreBuilder, OsgiContextStoreActivator

Field Summary
 
Fields inherited from interface com.sag.osami.api.context.IContextStore
CONTEXT_STORE_ID, TYPE_ALL, TYPE_DEREGISTERED, TYPE_REGISTERED
 
Constructor Summary
ContextStore(ISerializationHandler serializer, ISerializedContextStorage storage, java.lang.String storeID)
           
 
Method Summary
 void activateEventsForHandler(IContextHandler myHandler)
          Activate notification.
 void deactivateEventsForHandler(IContextHandler myHandler)
          Deactivate notification.
 void deregisterContextType(java.lang.String myType)
          Deregister context type in the ContextStore.
 void deregisterHandler(IContextHandler contextHandler)
          Deregister context handler.
 void deregisterHandlerForContextType(IContextHandler handler, java.lang.String contextType)
          Deregister the context handler for the given context type.
 java.lang.String[] getHandlersRegisteredContextTypes(IContextHandler handler)
          Returns all registered context types for committed handler.
 java.lang.String[] getRegisteredContextTypes()
          Returns all registered context types.
 ISerializationHandler getSerializationHandler()
           
 IContextStorage getStorage()
          Returns the storage handler of the context store, which handles storing, loading, querying and deleting context events
 java.lang.String getStoreID()
          Returns the ID of the ContextStore.
 boolean isRegisteredContextType(java.lang.String myType)
          Checks if given context type is registered in the ContextStore.
 void newContextEvent(ContextEvent cev)
          Insert a new context in the ContextStore.
 void newContextEvent(ContextEvent cev, boolean persist)
          Insert a new context in the ContextStore.
 void newContextEvent(java.lang.String originID, java.lang.String type, java.lang.Object data, java.util.Date date)
          Insert a new context with the given parameters in the ContextStore.
 void newContextEvent(java.lang.String originID, java.lang.String type, java.lang.Object data, java.util.Date date, boolean persist)
          Insert a new context with the given parameters in the ContextStore.
 void newContextEvent(java.lang.String originID, java.lang.String type, java.lang.String[] data, java.util.Date date, java.lang.String contextStoreOriginID)
          Creates a new context event with given parameters.
 void newContextEvent(java.lang.String originID, java.lang.String type, java.lang.String[] data, java.util.Date date, java.lang.String contextStoreOriginID, boolean persist)
          Creates a new context event with given parameters
 ContextEvent[] query(java.lang.String query, java.lang.Object... params)
          This method allows you to perform a query on the ContextStore database to get contexts with the specified properties
 java.lang.Iterable<ContextEvent> queryLazy(java.lang.String query, java.lang.Object... params)
          Lazy variant of IContextQuery.query(String, Object...), i.e. it loads one ContextEvent at a time during iteration.
 void registerContextType(java.lang.String myType)
          Register context type in the ContextStore.
 void registerHandler(IContextHandler contextHandler)
          Register a context handler for notification of new contexts (all types).
 void registerHandler(IContextHandler contextHandler, java.lang.String[] typeList)
          Register a context handler for notification of new contexts with any type in the given list.
 void registerHandlerForContextType(IContextHandler handler, java.lang.String contextType)
          Register the context handler for the given context type.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ContextStore

public ContextStore(ISerializationHandler serializer,
                    ISerializedContextStorage storage,
                    java.lang.String storeID)
Method Detail

registerHandler

public void registerHandler(IContextHandler contextHandler,
                            java.lang.String[] typeList)
Description copied from interface: IContextStore
Register a context handler for notification of new contexts with any type in the given list.

Specified by:
registerHandler in interface IContextStore
Parameters:
contextHandler - the context handler
typeList - the context type list

registerHandler

public void registerHandler(IContextHandler contextHandler)
Description copied from interface: IContextStore
Register a context handler for notification of new contexts (all types).

Specified by:
registerHandler in interface IContextStore
Parameters:
contextHandler - the context handler

registerHandlerForContextType

public void registerHandlerForContextType(IContextHandler handler,
                                          java.lang.String contextType)
Description copied from interface: IContextStore
Register the context handler for the given context type.

Specified by:
registerHandlerForContextType in interface IContextStore
Parameters:
handler - the context handler
contextType - the context type

deregisterHandler

public void deregisterHandler(IContextHandler contextHandler)
Description copied from interface: IContextStore
Deregister context handler.

Specified by:
deregisterHandler in interface IContextStore
Parameters:
contextHandler - the context handler

newContextEvent

public void newContextEvent(ContextEvent cev)
Description copied from interface: IContextStore
Insert a new context in the ContextStore.

Note that the actual context event object won't be stored as-is in the ContextStore but instead is re-packaged in a new ContextEvent data object. Also, the properties ID and contextStoreOriginID stored in the given object will be ignored and determined internally. This method exists for convenience only.

Specified by:
newContextEvent in interface IContextStore
Parameters:
cev - the context event to be inserted

newContextEvent

public void newContextEvent(ContextEvent cev,
                            boolean persist)
Description copied from interface: IContextStore
Insert a new context in the ContextStore.

Note that the actual context event object won't be stored as-is in the ContextStore but instead is re-packaged in a new ContextEvent data object. Also, the properties ID and contextStoreOriginID stored in the given object will be ignored and determined internally. This method exists for convenience only.

Specified by:
newContextEvent in interface IContextStore
Parameters:
cev - the context event to be inserted
persist - indicates whether context event should be persisted or not

newContextEvent

public void newContextEvent(java.lang.String originID,
                            java.lang.String type,
                            java.lang.Object data,
                            java.util.Date date)
Description copied from interface: IContextStore
Insert a new context with the given parameters in the ContextStore.

Specified by:
newContextEvent in interface IContextStore
Parameters:
originID - the origin id of the new context event
type - the type of the new context event
data - the data of the new context event
date - the date of the new context event

newContextEvent

public void newContextEvent(java.lang.String originID,
                            java.lang.String type,
                            java.lang.Object data,
                            java.util.Date date,
                            boolean persist)
Description copied from interface: IContextStore
Insert a new context with the given parameters in the ContextStore.

Specified by:
newContextEvent in interface IContextStore
Parameters:
originID - the origin id of the new context event
type - the type of the new context event
data - the data of the new context event
date - the date of the new context event
persist - indicates whether context event should be persisted or not

newContextEvent

public void newContextEvent(java.lang.String originID,
                            java.lang.String type,
                            java.lang.String[] data,
                            java.util.Date date,
                            java.lang.String contextStoreOriginID)
Description copied from interface: ISerializedContextReceiver
Creates a new context event with given parameters.

Specified by:
newContextEvent in interface ISerializedContextReceiver
Parameters:
originID - the origin ID
type - see context type
data - the serialized form of the payload
date - see context timestamp
contextStoreOriginID - the original context store name

newContextEvent

public void newContextEvent(java.lang.String originID,
                            java.lang.String type,
                            java.lang.String[] data,
                            java.util.Date date,
                            java.lang.String contextStoreOriginID,
                            boolean persist)
Description copied from interface: ISerializedContextReceiver
Creates a new context event with given parameters

Specified by:
newContextEvent in interface ISerializedContextReceiver
Parameters:
originID - the origin ID
type - see context type
data - the serialized form of the payload
date - see context timestamp
contextStoreOriginID - the original context store name
persist - indicates whether context event should be persisted or not

query

public ContextEvent[] query(java.lang.String query,
                            java.lang.Object... params)
Description copied from interface: IContextQuery
This method allows you to perform a query on the ContextStore database to get contexts with the specified properties

Specified by:
query in interface IContextQuery
Parameters:
query - the query to be executed
params - parameters which may occur in the query (e.g., using the ? syntax) and are bound accordingly (so escaping, quoting etc. is unnecessary)
Returns:
an array of IContextEvent[]s (which is empty if no contexts were found)

queryLazy

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

Specified by:
queryLazy in interface IContextQuery
Throws:
java.lang.UnsupportedOperationException - if the underlying storage implementation does not support lazy querying
See Also:
IContextQuery.query(String, Object...)

activateEventsForHandler

public void activateEventsForHandler(IContextHandler myHandler)
Description copied from interface: IContextStore
Activate notification. If handler had notification deactivated, now events are being delivered again.

Has no effect when notification was already active.

Specified by:
activateEventsForHandler in interface IContextStore
Parameters:
myHandler - the context handler

deactivateEventsForHandler

public void deactivateEventsForHandler(IContextHandler myHandler)
Description copied from interface: IContextStore
Deactivate notification. ContextStore no longer dispatches newContextEvents to the handler.

This is useful if the handler does some time-consuming operations while processing, or needs to be temporarily disabled. Despite the deactivation, the normal operation can be resumed without having to register again.

Has no effect when notification was already inactive.

Specified by:
deactivateEventsForHandler in interface IContextStore
Parameters:
myHandler - the context handler

deregisterContextType

public void deregisterContextType(java.lang.String myType)
Description copied from interface: IContextStore
Deregister context type in the ContextStore.

Specified by:
deregisterContextType in interface IContextStore
Parameters:
myType - the context type

isRegisteredContextType

public boolean isRegisteredContextType(java.lang.String myType)
Description copied from interface: IContextStore
Checks if given context type is registered in the ContextStore.

Specified by:
isRegisteredContextType in interface IContextStore
Returns:
boolean whether type is registered in the context store

getRegisteredContextTypes

public java.lang.String[] getRegisteredContextTypes()
Description copied from interface: IContextStore
Returns all registered context types.

Specified by:
getRegisteredContextTypes in interface IContextStore
Returns:
list of all registered context types

registerContextType

public void registerContextType(java.lang.String myType)
Description copied from interface: IContextStore
Register context type in the ContextStore.

This routine is useful, if a context source is not available in the beginning, but there are already handlers registering for future context events of the given type.

Specified by:
registerContextType in interface IContextStore
Parameters:
myType - the context type

deregisterHandlerForContextType

public void deregisterHandlerForContextType(IContextHandler handler,
                                            java.lang.String contextType)
Description copied from interface: IContextStore
Deregister the context handler for the given context type.

Specified by:
deregisterHandlerForContextType in interface IContextStore
Parameters:
handler - the context handler
contextType - the context type

getHandlersRegisteredContextTypes

public java.lang.String[] getHandlersRegisteredContextTypes(IContextHandler handler)
Description copied from interface: IContextStore
Returns all registered context types for committed handler.

Specified by:
getHandlersRegisteredContextTypes in interface IContextStore
Returns:
list of all registered context types

getStoreID

public java.lang.String getStoreID()
Description copied from interface: IContextStore
Returns the ID of the ContextStore.

Specified by:
getStoreID in interface IContextStore
Returns:
context store ID

getSerializationHandler

public ISerializationHandler getSerializationHandler()

getStorage

public IContextStorage getStorage()
Description copied from interface: IContextStore
Returns the storage handler of the context store, which handles storing, loading, querying and deleting context events

Specified by:
getStorage in interface IContextStore
Returns:
context storage handler