Writing Services

Introduction

This release provides three mechanisms for developing and deploying services, each with varying power and ease of use.

Writing custom service code

This is best for services that need to dynamically compute the results of queries. Classes such as SimpleService, ExpressionUtil, and ReqUtil are provided to automate many tasks.

Typically services are implemented by extending the SimpleService class. This class contains basic functionality such as incoming call reception, de-serialization, and return value serialization. This class also contains many utility routines designed to perform routine tasks as query error checking. Finally, it contains a very basic amount of support for automating implementation of posted queries.

See the SimpleService documentation for more information.

Example: CityTemp Service

The CityTemp service provides temperature information for cities. It demonstrates a "raw" service that receives query calls directly.

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 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 Service Interface.

Note that this wrapper currently does not support attribute requirements, a time limit, or dynamic attributes. It works as follows:

An incoming query is first turned into an SQL statement (attribReqs and timeLimit are currently ignored).
This query is then sent to the database for execution
If execution is not successful, an GeneralServiceException is thrown indicating the SQLException that occurred.
If execution is successful, a QueryResult is created and each each row in the result from the database is added to the QueryResult.
Each individual element in a row is checked to make sure it is a supported primitive type. If not, the objects toString() method is called to convert it to a string.
The QueryResult is sent back to the client.

Example

There is no example source code included for this since the wrapper is essentially a complete package. To run this, first start your database. Next make sure that you have a JDBC driver for your database in the classpath (in addition to the standard required .jar files mentioned in the installation notes). Now type "java edu.cmu.aura.service.dbw.WrapperService". This will list the required command line arguments. A batch file and a UNIX script are provided as an example. (If your SQL implementation requires a specific quote character you may specify it using -Dedu.cmu.aura.service.query.SQLQuoteChar= <your char>).

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.

See Service Database Documentation for more information.

Example: City Service

The City service is a simple service that provides information about cities. It demonstrates how the service database may be used. The database in this example is defined in an XML file, contains some custom initialization code, and contains code that can update the database at runtime.