Tracking Client API Overview

Introduction

Tracking Server provides near real-time distribution of GIS data delivered directly from collection point to viewing application. The Tracking Client APIs allow you to create client applications that receive GIS data from Tracking Server. Once the GIS data is received in the client application, you can do anything you want with it. For example, you may want to simply count the number of features that have been received, or you may want to display the features on an interactive map in real-time.

The Tracking Client APIs provide developer libraries for use on a variety of different platforms. These libraries are designed in such a way that the class names and the way the classes interact with one another is consistent across libraries. This means that if you learn to use the Connector class in Flex, you can easily use the same Connector class in Silverlight.

This conceptual section, along with the code samples and walkthroughs that follow, give an introductory overview of how to use the most important classes in the Tracking Client APIs, and these concepts apply to all the supported platforms. For information about interface names and function signatures in a specific platform, you should refer to the platform-specific API documentation.

Supported Platforms

• JavaScript
• Flex
• Silverlight
• Windows Phone
• Java
• .Net/WPF
• .Net Compact Framework
• Qt

Communication Model

The Tracking Client APIs use an asynchronous event-based model for interacting with the main classes. This means that when you call a method on a class, the method returns immediately without giving the results of the command. The result of the command is sent back some time later as an event called a "Response". Responses are delivered on a subscription basis, so listeners need to be created to handle them. Handler methods allow appropriate action to be taken, depending on whether a response indicates success or failure. In the case of a failure, errors can be handled appropriately using the error message returned as part of the response arguments. Responses have several types:

• Success - These responses indicate that the command was successfully executed to completion.
• Error (null) - These responses indicate that the command ended in an abnormal way.
• Observation Messages and Auxiliary Data - These are not responses to a specific command, but are data messages from the services you have subscribed to.
• General Error Event - These responses indicate that there was an error in the communication link while processing some of the messages. Unlike the Error response listed above, these are not responses to a specific command.

The Connector Class

The starting point for working with the Tracking Client APIs is the Connector class. This class facilitates most of the interactions between your client application and Tracking Server. The Connector class allows you to:

• Connect to Tracking Server (authentication is optional)
• Get information about tracking services available to you from Tracking Server
• Subscribe to tracking services from Tracking Server

Message Definitions

Data sent from Tracking Server to client applications conforms to a format called a message definition. The message definition is defined in Tracking Server ahead of time, and can be requested by client applications through the Connector class. A message definition consists of a name, spatial reference, time zone information, and an ordered attribute list.

Services and Subscriptions

Data is available from Tracking Server in conceptual units called "services". Each service has an associated message definition, and all messages sent from a service will conform to the structure of its message definition. Messages from a service will only be sent when a client subscribes to the service. A client application connecting to Tracking Server is not automatically subscribed to any services, so the client application will not immediately receive any data after connecting.

The client application must first request a list of services available from Tracking Server. After receiving a list of available services, the client application can subscribe to any of the services by name. Once the client application subscribes to a service, Tracking Server will begin sending messages for the requested service to the client application. Messages from this service will continue to be sent until action is taken by the client to unsubscribe from the service.

Tip:

If authentication is used to connect to Tracking Server, the list of services available to you depends on the user name and password you use to connect. The administrator of Tracking Server can configure which services are available to different users.

Simple and Complex Services

There are two types of tracking services available from Tracking Server - Simple and Complex. Simple services are more common and more straightforward to work with. In a simple service, every data message contains all the available information about the object being tracked. In a complex service, the information is split into two parts: dynamic data and static data. The dynamic portion of the data changes with every observation of a tracked object (such as the location and speed of a moving object) and static data remains the same (such as the model or engine type of a vehicle).

Data in a complex service is broken into two parts to maximize efficiency. If a significant amount of the data is static, then it is a waste of bandwidth to send the same data repeatedly across the network. Instead, the static data is separated from the dynamic data and only sent across the network once. Complex services can be defined to communicate data for stationary objects (such as traffic sensors), in which case the geometry is transmitted in the static part of the data, or moving objects (such as airplanes), in which case the geometry is transmitted in the dynamic part of the data.

For complex services, the properties of a tracked object are divided into two messages - the Observation and the Auxiliary Data. The Observation message contains properties of the object that change over time, and the Auxiliary Data message contains the properties that are static. In a Simple service, the Observation and Auxiliary Data parts are combined into one, and the client only receives Observation messages. In a Complex service, Observation and Auxiliary Data messages are sent separately.

For all services, a timestamp attribute is required and must be included in the Observation message. For complex services, the Observation and the Auxiliary Data messages must contain an attribute identified as the Event ID. The Event ID is used to join incoming Observation messages with the correct Auxiliary Data message.