Aura Contextual Service Interface

Java Implementation

Service Provider Release 2.3

Introduction

The Aura Contextual Service Interface is a framework for that allows simple information providing services to communicate with clients. This software package provides Java libraries for developing information providing services as well as for developing clients to access these services.

This document provides a brief overview of various topics and also provides links to more detailed information (found in the doc subdirectory). 

Note that the Contextual Service Interface was previously referred to as the Primitive Service Interface. The API retains this terminology.

Contents of this Document

Overview of the Aura Contextual Service Interface

Requirements

Writing Clients

Writing Services

Tools

Installation

Related Documentation

API Documentation - A Javadoc reference to the API contained in this release.

Note for Implementors - Notes on implementing the Aura Contextual Service Interface Protocol. Not required reading, but useful for understanding what's happening on the wire.

Overview of the Aura Contextual Service InterfaceWriting Clients

See doc/ServiceInterfaceOverview.html for an overview of the service interface.

See doc/ContextualServices.pdf for a more detailed description of the Contextual Services Interface.

Requirements

You will need JDK 1.4 or greater in order to use this package for development. You will need either JDK 1.4 or JRE 1.4 to run code developed with this package.

Writing Clients

This release provides four methods for clients to create queries and send them to services:

  1. Using attribute retrieval calls - The simplest method for communicating with a service; clients simply specify the name attribute they are looking for. 
  2. Specifying each element of the query - Useful for complete control over a query. Clients are able to specify constraints, such as accuracy, that they require for elements of the query.
  3. Creating a Query object - Provides a convenient mechanism for packaging elements of a query in a single package. Full control of the query is allowed with this method as well.
  4. Providing an SQL like string - Useful for improving code concision. Clients provide a SQL like string to a parser and receive a Query object in return.

See doc/WritingClients.html for more information on writing clients.

Writing Services

This release provides three methods for developing Aura Contextual Services:

  1. Writing custom service code - This is best for services that need to dynamically compute the results of queries. Classes are provided to automate many tasks.
  2. Using an SQL database - This is best for instances when the service can be modeled as a database. For this case, a wrapper is provided in this distribution that converts incoming Aura Contextual Service Interface queries into SQL queries. It then sends these queries to the database via JDBC and sends the results back to the client via the Aura Contextual Service Interface.
  3. Using static data provided in XML files - This is best for cases when simple static data needs to be provided, and it is inconvient to use a full blown database. This method also supports variable length schema.

See doc/WritingServices.html for more information on writing services.

Tools

The GenericClient tool provides an SQL like interface for sending queries to arbitrary services.

Installation

After unjarring the distribution file, you will need to set your CLASSPATH so that it includes lib/aurasvc.jar .

For running the pre-compiled examples, the following environment variables should be set (Windows examples are shown; Unix examples are similar):

Clients that need callbacks from servers must tell the server their IP address. The API should take care of this for you, but in certain circumstances clients may need to control this explicitly. You usually should not need to worry about this, but if you need to, this is done by setting the Java property edu.cmu.aura.service.net.HostName (e.g., if your client's IP address was 169.254.0.0 you might use the command: java -Dedu.cmu.aura.service.net.HostName= 169.254.0.0 MyClient ). If you need to do this, you should set the variable HOSTNAME before running the precompiled examples. Again, the majority of the time this step should be unnecessary.

Simplified Directory Structure

                               AURASVC_HOME
                                    |
                  ---------------------------------------
                  |                 |                   |								
                 lib               doc               examples
                                    |                   |
                                   api              ---------
                                                    |       |
                                                 clients  services

lib - contains the binary version of the service provider and client libraries
doc - contains the release documentation
examples - contains examples of services and clients that access those services