Service Interface Overview

Introduction

The Aura Contextual Service Interface defines a standard mechanism for services to provide applications with information such as the location of a given user or device, expected network throughput, the battery levels of a given set of devices, etc. In addition, a small set of contextual services is proposed that Aura applications can depend on for information.

The diagram below shows the proposed classes of services. These services are divided into two types: entity based services (shown in blue rectangles) that provide information about a specific class of entities, and relationship based services (shown in tan ovals) that track the relationship between two classes of entities.

API

The fundamental mechanism clients use to retrieve information from services is a query where clients retrieve attributes of entities tracked by services or attributes of relationships tracked by services. Service attributes come in two forms: 1 - Static attributes which change rarely; 2 - Dynamic attributes that may change constantly. Dynamic attributes also have several meta-attributes associated with them: confidence & accuracy (a confidence interval), updateTime (when the attribute value was measured), and sample interval (a period of time over which the attribute value was measured). Service clients may specify "requirements" on these attributes (e.g. a confidence of 0.9). Note that not all services will provide all meta-attributes for dynamic attributes. Services may also ...

The query call accepts five parameters:

• sAttribs - selects the attributes that are to be returned. A null value indicates that all attributes are to be selected.
• serviceNames - selects the name of the service being queried (this parameter is merely an implementational convenience allowing more than one service to be implemented together). A null value may be used when there is only one service listening.
• expression - an expression describing the desired information. (See QueryExpressions.html.) A null value indicates that all entries in the service are to be retrieved.
• attribReqs - requirements on attributes (both in the sAttribs parameter as well as the expression parameter). This applies only to dynamic attributes. A null value indicates no requirements are in effect.
• timeLimit - a hint to the service on the time within which the client should be serviced.

The result of a query is a QueryResult structure that includes the time the query executed, a flag indicating whether all the constraints specified in the query were met, and a list of service entries satisfying the query where each entry contains one or more attributes.

The rich functionality provided to clients by this call could impose a large burden on services. For this reason, services are not required to support arbitrary expressions or attribute requirements . Services that receive a query that they do not support return an error when a client submits a query utilizing an unsupported feature. (Examples where this could occur include, but are not limited to, an expression that is too rich, or an expression that is not selective enough).

The other functions defined as part of the service interface are simply extensions of the query function. (See the javadoc documentation for the interface PrimitiveService for details of the these functions.)

Implementation

See the Implementation Notes for a rough guide on implementing the service interface.