at.ac.tuwien.infosys.sm4all.copal.api
Class ContextQuery

java.lang.Object
  extended by at.ac.tuwien.infosys.sm4all.copal.api.ContextQuery
Direct Known Subclasses:
ActionQuery, ProcessedEventQuery

public class ContextQuery
extends Object

This class is used by the ContextListeners to tell on which ContextEvents the listeners are interested in. Two properties are used to select ContextEvents:

Author:
fei, sanjin

Constructor Summary
ContextQuery(String name, String eventType)
          Create instance of the ContextQuery.
ContextQuery(String name, String eventType, String criteria)
          Creates an instance of ContextQuery.
 
Method Summary
 void attach(ContextQueryObserver observer)
          Attach specified ContextQueryObserver so it will in future receive notifications of this ContextQuery state changes.
 void destroy()
          Destroys this ContextQuery.
 void detach(ContextQueryObserver observer)
          Detach specified ContextQueryObserver so it will not receive any future notifications of this ContextQuery state changes.
 void detachAll()
          Detach all ContextQueryObservers.
 boolean equals(Object obj)
          Compares this ContextQuery to the specified Object.
 String getCriteria()
           
 String getEventType()
           
 ContextListener[] getListeners()
           
 String getName()
           
 boolean hasCriteria()
           
 int hashCode()
          Returns hash code for this ContextQuery.
 boolean isDestroyed()
           
 boolean isRegistered(String listenerName)
          Checks if a ContextListener with specified name is currently registered.
 void onEvent(Document event)
          This method is called when a context event with same event name occurs for which the criteria is satisfied.
 void register(ContextListener listener)
          Register specified ContextListener with this ContextQuery .
 void unregister(String listenerName)
          Unregister ContextListener with specified name from this ContextQuery.
 void unregisterAll()
          Unregister all registered ContextListeners from this ContextQuery.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ContextQuery

public ContextQuery(String name,
                    String eventType,
                    String criteria)
Creates an instance of ContextQuery. The name should be globally unique, meaning that if two ContextQuerys have same name then their eventTypes and criterias are equal. The eventType is name of ContextEventType on which criteria is executed. The criteria is the logical statement which further separates the events of interest. If ContextQuery should catch all eventType events, we set criteria to be null or blank string or use ContextQuery(String, String) constructor.

Parameters:
name - the globally unique name of the ContextQuery.
eventType - the name of ContextEventType.
criteria - the logical expression of the ContextQuery.
Throws:
NullPointerException - if specified name or event type is null.
IllegalArgumentException - if specified name or event type is an empty or blank string.

ContextQuery

public ContextQuery(String name,
                    String eventType)
Create instance of the ContextQuery. The name should be globally unique, meaning that if two ContextQuerys have same name then their eventTypes and criterias are equal. The eventType is name of ContextEventType to be caught.

Parameters:
name - the globally unique name of the ContextQuery.
eventType - the name of ContextEventType.
Throws:
NullPointerException - if specified name or event type is null.
IllegalArgumentException - if specified name or event type is an empty or blank string.
Method Detail

getName

public String getName()
Returns:
the globally unique name of the ContextQuery.

getEventType

public String getEventType()
Returns:
the name of ContextEventType.
See Also:
ContextEventType.getName()

getCriteria

public String getCriteria()
Returns:
the logical expression the ContextQuery.

hasCriteria

public boolean hasCriteria()
Returns:
if this ContextQuery has the criteria defined.

isDestroyed

public boolean isDestroyed()
Returns:
if this ContextQuery is destroyed.

register

public void register(ContextListener listener)
              throws ListenerAlreadyRegisteredException,
                     QueryDestroyedException
Register specified ContextListener with this ContextQuery . If event is caught, for which the criteria evaluates to true, the specified ContextListener will be invoked.

Parameters:
listener - the ContextListener.
Throws:
ListenerAlreadyRegisteredException - if the ContextListener with same name is already registered with this ContextQuery.
NullPointerException - if specified ContextListener is null.
QueryDestroyedException - if ContextQuery has been previously destroyed.

unregister

public void unregister(String listenerName)
                throws ListenerNotRegisteredException
Unregister ContextListener with specified name from this ContextQuery. The ContextListener will not receive any further events from this ContextQuery.

Parameters:
listenerName - the name of the ContextListener.
Throws:
ListenerNotRegisteredException - if the ContextListener with specified name is not registered with this ContextQuery.
NullPointerException - if specified name of the ContextListener is null.

unregisterAll

public void unregisterAll()
Unregister all registered ContextListeners from this ContextQuery. The ContextListeners will not receive any further events from this ContextQuery.


destroy

public void destroy()
             throws QueryDestroyedException
Destroys this ContextQuery. All registered ContextListeners will be unregistered and any future registration of a ContextListener and receiving of events will not be possible.

Throws:
QueryDestroyedException - if ContextQuery has been already destroyed.

onEvent

public void onEvent(Document event)
             throws QueryDestroyedException
This method is called when a context event with same event name occurs for which the criteria is satisfied. This method in return calls all registered ContextListeners with specified event.

Parameters:
event - occurred event.
Throws:
QueryDestroyedException - if ContextQuery has been previously destroyed.

isRegistered

public boolean isRegistered(String listenerName)
Checks if a ContextListener with specified name is currently registered.

Parameters:
listenerName - the name of the ContextListener.
Returns:
true> if such ContextListener is registered; false otherwise.

getListeners

public ContextListener[] getListeners()
Returns:
all ContextListeners which are registered with this query.

attach

public void attach(ContextQueryObserver observer)
Attach specified ContextQueryObserver so it will in future receive notifications of this ContextQuery state changes.

Parameters:
observer - the ContextQueryObserver.

detach

public void detach(ContextQueryObserver observer)
Detach specified ContextQueryObserver so it will not receive any future notifications of this ContextQuery state changes.

Parameters:
observer - the ContextQueryObserver.

detachAll

public void detachAll()
Detach all ContextQueryObservers.


hashCode

public int hashCode()
Returns hash code for this ContextQuery. The hash code for a ContextQuery object is hash code of its name.

Overrides:
hashCode in class Object
Returns:
a hash code value for this ContextQuery.

equals

public boolean equals(Object obj)
Compares this ContextQuery to the specified Object. The result is true if and only if the argument is not null and is a ContextQuery object that has same name as this ContextQuery.

Overrides:
equals in class Object
Parameters:
obj - the Object to compare this ContextQuery against.
Returns:
true if ContextQuerys are equal; false otherwise.


Copyright © 2010 Distributed Systems Group, Vienna University of Technology. All Rights Reserved.