com.sag.osami.api.context
Interface IContextStore

All Superinterfaces:
IContextQuery
All Known Subinterfaces:
ISerializedContextReceiver
All Known Implementing Classes:
ContextStore

public interface IContextStore
extends IContextQuery

The ContextStore manages a persistent store for context events and manages context providers and consumers through a uniform interface. Context events are dispatched to registered handlers according to the registered types of the handlers. Handlers can change the registration for context types during their lifetime.

Since version 1.1.0, the semantics of the newContextEvent methods changed substantially: the events created this way are no longer processed synchronously. Handlers execute their handling code in own threads.

Also since version 1.1.0, ContextStores now feature a (ideally unique) ID. This ID might be used in future releases, where communication between ContextStores (e.g. on different hosts) might be possible.

OSGi notice: In OSGi environments, the ContextStore is registered as a service providing this interface.

See Also:
IContextHandler

Field Summary
static java.lang.String CONTEXT_STORE_ID
           
static java.lang.String TYPE_ALL
          This constant is used as a context type when a handler should receive all context events
static java.lang.String TYPE_DEREGISTERED
           
static java.lang.String TYPE_REGISTERED
           
 
Method Summary
 void activateEventsForHandler(IContextHandler ctxHandler)
          Activate notification.
 void deactivateEventsForHandler(IContextHandler ctxHandler)
          Deactivate notification.
 void deregisterContextType(java.lang.String ctxType)
          Deregister context type in the ContextStore.
 void deregisterHandler(IContextHandler ctxHandler)
          Deregister context handler.
 void deregisterHandlerForContextType(IContextHandler ctxHandler, java.lang.String ctxType)
          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.
 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 ctxEvent)
          Insert a new context in the ContextStore.
 void newContextEvent(ContextEvent ctxEvent, 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 registerContextType(java.lang.String ctxType)
          Register context type in the ContextStore.
 void registerHandler(IContextHandler ctxHandler)
          Register a context handler for notification of new contexts (all types).
 void registerHandler(IContextHandler ctxHandler, java.lang.String[] ctxTypes)
          Register a context handler for notification of new contexts with any type in the given list.
 void registerHandlerForContextType(IContextHandler ctxHandler, java.lang.String ctxType)
          Register the context handler for the given context type.
 
Methods inherited from interface com.sag.osami.api.context.IContextQuery
query, queryLazy
 

Field Detail

CONTEXT_STORE_ID

static final java.lang.String CONTEXT_STORE_ID
See Also:
Constant Field Values

TYPE_REGISTERED

static final java.lang.String TYPE_REGISTERED
See Also:
Constant Field Values

TYPE_DEREGISTERED

static final java.lang.String TYPE_DEREGISTERED
See Also:
Constant Field Values

TYPE_ALL

static final java.lang.String TYPE_ALL
This constant is used as a context type when a handler should receive all context events

See Also:
Constant Field Values
Method Detail

newContextEvent

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.

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

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.

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

void newContextEvent(ContextEvent ctxEvent)
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.

Parameters:
ctxEvent - the context event to be inserted

newContextEvent

void newContextEvent(ContextEvent ctxEvent,
                     boolean persist)
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.

Parameters:
ctxEvent - the context event to be inserted
persist - indicates whether context event should be persisted or not

registerHandler

void registerHandler(IContextHandler ctxHandler)
Register a context handler for notification of new contexts (all types).

Parameters:
ctxHandler - the context handler

registerHandler

void registerHandler(IContextHandler ctxHandler,
                     java.lang.String[] ctxTypes)
Register a context handler for notification of new contexts with any type in the given list.

Parameters:
ctxHandler - the context handler
ctxTypes - the context type list

deregisterHandler

void deregisterHandler(IContextHandler ctxHandler)
Deregister context handler.

Parameters:
ctxHandler - the context handler

activateEventsForHandler

void activateEventsForHandler(IContextHandler ctxHandler)
Activate notification. If handler had notification deactivated, now events are being delivered again.

Has no effect when notification was already active.

Parameters:
ctxHandler - the context handler

deactivateEventsForHandler

void deactivateEventsForHandler(IContextHandler ctxHandler)
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.

Parameters:
ctxHandler - the context handler

registerContextType

void registerContextType(java.lang.String ctxType)
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.

Parameters:
ctxType - the context type

deregisterContextType

void deregisterContextType(java.lang.String ctxType)
Deregister context type in the ContextStore.

Parameters:
ctxType - the context type

isRegisteredContextType

boolean isRegisteredContextType(java.lang.String myType)
Checks if given context type is registered in the ContextStore.

Parameters:
ctxType - the context type to be checked
Returns:
boolean whether type is registered in the context store

getRegisteredContextTypes

java.lang.String[] getRegisteredContextTypes()
Returns all registered context types.

Returns:
list of all registered context types

getHandlersRegisteredContextTypes

java.lang.String[] getHandlersRegisteredContextTypes(IContextHandler handler)
Returns all registered context types for committed handler.

Returns:
list of all registered context types

registerHandlerForContextType

void registerHandlerForContextType(IContextHandler ctxHandler,
                                   java.lang.String ctxType)
Register the context handler for the given context type.

Parameters:
ctxHandler - the context handler
ctxType - the context type

deregisterHandlerForContextType

void deregisterHandlerForContextType(IContextHandler ctxHandler,
                                     java.lang.String ctxType)
Deregister the context handler for the given context type.

Parameters:
ctxHandler - the context handler
ctxType - the context type

getStoreID

java.lang.String getStoreID()
Returns the ID of the ContextStore.

Returns:
context store ID

getStorage

IContextStorage getStorage()
Returns the storage handler of the context store, which handles storing, loading, querying and deleting context events

Returns:
context storage handler