edu.cmu.aura.service
Interface PrimitiveService

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

Database, PrimitiveServiceStub, SimpleService

public interface PrimitiveService

extends java.rmi.Remote

PrimitiveService is the Remote interface implemented by generic primitive services. This is the main interface used to access Aura primitive services.

The query method is the fundamental method used to retrieve information from services. The other methods are mainly extensions of the query method.

Note that not all services will support all methods; however, all services will at least support query. Also, services may decide what types of queries they support and whether or not they support attribute requirements. If a client attempts to use too rich an expression services will throw an exception. Similarly, specifying an attribute requirement that is not supported will result in an exception (as long as the service is implemented correctly). Clients should know in advance what types of functionality, expressions, and attribute requirements the services they access support.

Note that in general there are two types of services: entity based and relation based. An entity based service might be one that provides the address of people for example. A relation based service might provide information on the relationship between people and devices. Relation based services that track a dynamic relation may use a special dynamic attribute named "relation" in order to provide information about the relationship. (When referring to this special attribute name, the constant RELATION_ATTRIB is preferred to directly using "relation" in your code).

Field Summary

static java.util.ArrayList	ALL_ATTRIBS Constant for sAttribs argument indicating that all attributes are to be returned.
static java.util.ArrayList	ANY_CHANGE Constant for triggerAttribs argument and the triggerDeltas argument specifying that any change in the attributes should cause the trigger to fire.
static long	DEFAULT_EXEC_INTERVAL Constant for execInterval argument indicating that the service may decide when to execute the query or check the trigger.
static java.util.ArrayList	DEFAULT_SERVICE Constant for serviceNames argument indicating that the default service is to be queried.
static java.lang.String	DEFAULT_SERVICE_NAME Constant for serviceName argument indicating that the default service is to be contacted (used in remove operations).
static java.util.ArrayList	NO_REQS Constant for attribReqs argument indicating that no attribute requirements are needed.
static long	NO_TIME_LIMIT Constant for timeLimit argument indicating that there is no hard time limit.
static java.lang.String	RELATION_ATTRIB Constant indicating the name of the attribute that tracks properties of dynamic relationships.
static ExpressionNode	SELECT_ALL Constant for expression argument indicating attributes for all entities or relations tracked by the service are to be returned.

Method Summary

int	postCondTrigger(java.util.ArrayList sAttribs, java.util.ArrayList serviceNames, ExpressionNode expression, java.util.ArrayList attribReqs, long timeLimit, long execInterval, ExpressionNode triggerExpression, edu.cmu.aura.service.rpc.RemoteReference queryClient) Post a trigger that is to execute when a particular condition is met.
int	postModTrigger(java.util.ArrayList sAttribs, java.util.ArrayList serviceNames, ExpressionNode expression, java.util.ArrayList attribReqs, long timeLimit, long execInterval, java.util.ArrayList triggerAttribs, java.util.ArrayList triggerDeltas, edu.cmu.aura.service.rpc.RemoteReference queryClient) Post a trigger that is to execute when any one of a given set of attributes changes by a specified amount.
int	postQuery(java.util.ArrayList sAttribs, java.util.ArrayList serviceNames, ExpressionNode expression, java.util.ArrayList attribReqs, long timeLimit, long execInterval, edu.cmu.aura.service.rpc.RemoteReference queryClient) Query a service repeatedly at a regular interval.
QueryResult	query(java.util.ArrayList sAttribs, java.util.ArrayList serviceNames, ExpressionNode expression, java.util.ArrayList attribReqs, long timeLimit) Query a service.
void	removeQuery(java.lang.String serviceName, int queryID) Remove a recurrent query.
void	removeTrigger(java.lang.String serviceName, int queryID) Remove a trigger.

Field Detail

ALL_ATTRIBS

public static final java.util.ArrayList ALL_ATTRIBS

Constant for sAttribs argument indicating that all attributes are to be returned. Defined as null by the Primitive Service Interface.

DEFAULT_SERVICE

public static final java.util.ArrayList DEFAULT_SERVICE

Constant for serviceNames argument indicating that the default service is to be queried. Defined as null by the Primitive Service Interface.

DEFAULT_SERVICE_NAME

public static final java.lang.String DEFAULT_SERVICE_NAME

Constant for serviceName argument indicating that the default service is to be contacted (used in remove operations). Defined as null by the Primitive Service Interface.

SELECT_ALL

public static final ExpressionNode SELECT_ALL

Constant for expression argument indicating attributes for all entities or relations tracked by the service are to be returned. Defined as null by the Primitive Service Interface.

NO_REQS

public static final java.util.ArrayList NO_REQS

Constant for attribReqs argument indicating that no attribute requirements are needed. Defined as null by the Primitive Service Interface.

NO_TIME_LIMIT

public static final long NO_TIME_LIMIT

Constant for timeLimit argument indicating that there is no hard time limit. Defined as null by the Primitive Service Interface.

See Also:

Constant Field Values

DEFAULT_EXEC_INTERVAL

public static final long DEFAULT_EXEC_INTERVAL

Constant for execInterval argument indicating that the service may decide when to execute the query or check the trigger. Defined as null by the Primitive Service Interface.

See Also:

Constant Field Values

ANY_CHANGE

public static final java.util.ArrayList ANY_CHANGE

Constant for triggerAttribs argument and the triggerDeltas argument specifying that any change in the attributes should cause the trigger to fire. Defined as null by the Primitive Service Interface.

RELATION_ATTRIB

public static final java.lang.String RELATION_ATTRIB

Constant indicating the name of the attribute that tracks properties of dynamic relationships. Defined as "relation" by the Primitive Service Interface.

See Also:

Constant Field Values

Method Detail

query

public QueryResult query(java.util.ArrayList sAttribs,
                         java.util.ArrayList serviceNames,
                         ExpressionNode expression,
                         java.util.ArrayList attribReqs,
                         long timeLimit)
                  throws java.rmi.RemoteException,
                         ServiceException

Query a service.

Parameters:

sAttribs - attribsutes to select. ALL_ATTRIBS indicates that all attributes are to be selected.

serviceNames - names of services to retrieve attributes from. DEFAULT_SERVICE may be used if there is only one service listening on a given port.

expression - expression selecting which entities or relations in the service should be returned. SELECT_ALL indicates all entities are to be selected.

attribReqs - requirements on dynamic attributes. NO_REQS indicates there are no requirements in effect.

timeLimit - this is used by clients to inform the service on when they need the results by. This may also be viewed as a suggestion on how hard to work to retrieve the results. NO_TIME_LIMIT indicates that the client has no hard limit on how long the query should take; though a client will likely still desire reasonably fast execution.

Returns:

the QueryResult of the query.

java.rmi.RemoteException

ServiceException

postQuery

public int postQuery(java.util.ArrayList sAttribs,
                     java.util.ArrayList serviceNames,
                     ExpressionNode expression,
                     java.util.ArrayList attribReqs,
                     long timeLimit,
                     long execInterval,
                     edu.cmu.aura.service.rpc.RemoteReference queryClient)
              throws java.rmi.RemoteException,
                     ServiceException

Query a service repeatedly at a regular interval.

Parameters:

sAttribs - attribsutes to select. ALL_ATTRIBS indicates that all attributes are to be selected.

serviceNames - names of services to retrieve attributes from. DEFAULT_SERVICE may be used if there is only one service listening on a given port.

expression - expression selecting which entities or relations in the service should be returned. SELECT_ALL indicates all entities are to be selected.

attribReqs - requirements on dynamic attributes. NO_REQS indicates there are no requirements in effect.

timeLimit - this is used by clients to inform the service on when they need the results by. This may also be viewed as a suggestion on how hard to work to retrieve the results. NO_TIME_LIMIT indicates that the client has no hard limit on how long the query should take; though a client will likely still desire reasonably fast execution.

execInterval - interval at which to execute the query. DEFAULT_EXEC_INTERVAL may be specified if they service is to select the interval at which the query should execute.

queryClient - the client that should be informed when this query executes.

Returns:

the id of the posted query.

java.rmi.RemoteException

ServiceException

removeQuery

public void removeQuery(java.lang.String serviceName,
                        int queryID)
                 throws java.rmi.RemoteException,
                        ServiceException

Remove a recurrent query.

Parameters:

serviceName - name of the service to remove the query from.

queryID - the ID of the query to remove.

java.rmi.RemoteException

ServiceException

postCondTrigger

public int postCondTrigger(java.util.ArrayList sAttribs,
                           java.util.ArrayList serviceNames,
                           ExpressionNode expression,
                           java.util.ArrayList attribReqs,
                           long timeLimit,
                           long execInterval,
                           ExpressionNode triggerExpression,
                           edu.cmu.aura.service.rpc.RemoteReference queryClient)
                    throws java.rmi.RemoteException,
                           ServiceException

Post a trigger that is to execute when a particular condition is met. Note that a trigger may be regarded as a posted query that executes at a particular interval. A client may request that a service check constantly by specifying an execInterval of DEFAULT_EXEC_INTERVAL, but a service is free to decide what interval to check at if it has no easy mechanism for checking constantly.

Parameters:

sAttribs - attribsutes to select. ALL_ATTRIBS indicates that all attributes are to be selected.

serviceNames - names of services to retrieve attributes from. DEFAULT_SERVICE may be used if there is only one service listening on a given port.

expression - expression selecting which entities or relations in the service should be returned. SELECT_ALL indicates all entities are to be selected.

attribReqs - requirements on dynamic attributes. NO_REQS indicates there are no requirements in effect.

timeLimit - this is used by clients to inform the service on when they need the results by. This may also be viewed as a suggestion on how hard to work to retrieve the results. NO_TIME_LIMIT indicates that the client has no hard limit on how long the processing should take; though a client will likely still desire reasonably fast execution.

execInterval - interval at which to check the trigger.

triggerExpression - condition indicating when to fire the trigger.

queryClient - the client that should be informed when this trigger executes.

Returns:

the id of the posted trigger.

java.rmi.RemoteException

ServiceException

postModTrigger

public int postModTrigger(java.util.ArrayList sAttribs,
                          java.util.ArrayList serviceNames,
                          ExpressionNode expression,
                          java.util.ArrayList attribReqs,
                          long timeLimit,
                          long execInterval,
                          java.util.ArrayList triggerAttribs,
                          java.util.ArrayList triggerDeltas,
                          edu.cmu.aura.service.rpc.RemoteReference queryClient)
                   throws java.rmi.RemoteException,
                          ServiceException

Post a trigger that is to execute when any one of a given set of attributes changes by a specified amount. Note that a trigger may be regarded as a posted query that executes at a particular interval. A client may request that a service check constantly by specifying an execInterval of DEFAULT_EXEC_INTERVAL, but a service is free to decide what interval to check at if it has no easy mechanism for checking constantly.

Parameters:

sAttribs - attribsutes to select. ALL_ATTRIBS indicates that all attributes are to be selected.

serviceNames - names of services to retrieve attributes from. DEFAULT_SERVICE may be used if there is only one service listening on a given port.

expression - expression selecting which entities or relations in the service should be returned. SELECT_ALL indicates all entities are to be selected.

attribReqs - requirements on dynamic attributes. NO_REQS indicates there are no requirements in effect.

timeLimit - this is used by clients to inform the service on when they need the results by. This may also be viewed as a suggestion on how hard to work to retrieve the results. NO_TIME_LIMIT indicates that the client has no hard limit on how long the processing should take; though a client will likely still desire reasonably fast execution.

execInterval - interval at which to check the trigger.

triggerAttribs - attributes to watch for changes.

triggerDeltas - amount of change that will cause the trigger to fire for the corresponding attribute.

queryClient - the client that should be informed when this trigger executes.

Returns:

the id of the posted trigger.

java.rmi.RemoteException

ServiceException

removeTrigger

public void removeTrigger(java.lang.String serviceName,
                          int queryID)
                   throws java.rmi.RemoteException,
                          ServiceException

Remove a trigger.

Parameters:

serviceName - name of the service to remove the query from.

queryID - the ID of the query to remove.

java.rmi.RemoteException

ServiceException