AGTEK Lib (henceforth called “Lib” for keyboard convenience) is a library of code to provide a repository of common functionality for Android and Java applications. While the potential exists for generic Java applications, the focus is currently Android, so using this Library in a generic Java application may require some effort (particularly repackaging, building proper build scripts, etc.) It's also possible that a generic Java platform library needs to exist separately from the Android lib. Generic Java would be usable in in Android, which Java Swing would not be (much like Android specific functionality). Note for future thoughts, split the library 3 ways (generic, Android Platform specific, Java Platform specific).

This document is intended to give the reader an overview, with some taste (via simple code snippets) of how pieces of the Lib are to be used. This documented is not intended document each class, member, or method. The Javadocs are to be used for detailed reference on call level documentation. All components of the Lib are required to be Javadoc'ed.

AGTEK Lib is a collection of different functional groups. Largely the groups are intended to be interoperable functional classes. It's possible that some functional groups are intraoperable, but that is not a design requirement for the Lib. It is envisioned that the Lib will grow, somewhat organically as the Android product suite expands. While inclusion of a new functional group is encouraged, a group must exhibit some of the following characteristics:

• Be written in an application neutral manner. Under no circumstances must a Lib component be aware of what application is using it.
• A library should be usable by more than one application. In otherwords, it should be obvious that the functional group is useful in a wider context. If you aren't sure, keep it with the originating application, and move it to the Lib when it it is needed by the second application.
• Unit tests must be provided for all appropriate components. It is recognized that when dealing with external devices, or servers, you've gone beyond the ability to unit test the code. In all circumstances the code needs to be tested and provable correct before being checked in to the Lib.
• All classes and methods must be JavaDoc'ed.
• Tags will be layed upon the Subversion project to aid configuration management and rebuilding repeatable / secure applications. Generally developers should do their work on the HEAD of the trunk.

The following functional groups, organized by their major package are currently part of the Lib. A longer description of each group follows this section. Each section may include links other pages discussing the architecture of the functionality or how to extend it.

• com.agtek.access - The Android Asynchronous Task library for AGTEK Access. This functionality provides asynchronous wrappers around AGTEK Access functionality so it can be used within the Android UI environment.
• com.agtek.geometry - The generic geometric math package.
• com.agtek.io - IO utilities for Android. This package provides utilities useful for operating within the Android IO system, and defines the rules for using the Android storage cards by AGTEK products.
• com.agtek.license - The interface to the AGTEK Acecss License system. This is convenience functionality to provide a wrapper for dealing with the Access License system.
• com.agtek.location - The Android Location Manager framework. The package provides a semi-drop in replacement for the Android LocationManager which supports very similar interfaces as the Android manager. This package also supports drivers for typical Bluetooth (or other) devices used by AGTEK applications.

The Android LocationManager interface isolates the application from the details of dealing with the built in Location Provider devices. Android currently support approximately three different providers; built in GPS, computed locations (based on WIFI & Cell Tower), and mock locations. Only the first two provide semi-reliable location information for applications, while the “mock” device is only useful for application development.

The Android LocationManager doesn't currently allow the ability to extend or add providers for additional devices, a key AGTEK requirement. The AGTEK LocationManager was designed with following goals in mind:

• Support additional location devices
• Follow the basic LocationListener pattern
• Allow application packaging choice. Applications have varying footprint requirements, the manager must be small.

The Android LocationManager provides interface methods for working with testing, development, and “normal” use. Our approach is to treat all of these factors the same. Testing and development all provide locations through the same interfaces as the “normal” devices. The LocationManager represents physical location providing instruments with two different object types; LocationDevice and LocationProvider. The LocationDevice class describes the instrument, but doesn't interact with it, and can be thought of as a “File Descriptor”. A LocationProvider will consume the data stream from the location instrument, and actually provide the Location updates to the application (mediated by the LocationFramework).

The Application generally does not interact directly with the LocationProvider in use. Rather the Application will do most of the work using the LocationManager. The AGTEK LocationManager is retrieved using a Singleton pattern instead of using an Android OS interface;

import com.agtek.location.LocationManager;
public MyClass extends activity implements LocationListener
{
   // ...
   LocationManager m_locationManager = LocationManager.GetInstance(this);
   // ...
}

When getting the instance of the LocationManager, you must pass in an Activity context. This is required so the LocationManager can access the Bluetooth manager. The Bluetooth manager is required in order to support most of the RTK based devices.

The Application needs to get a LocationDevice to request updates. To get the device initialized and running, the user must first choose a device, then the application can request updates (although depending on the application, some devices may be hardwired);

   public class MyClass 
   {
      // ...
      LocationDevice deviceChoices[] = m_locationManager.getDevices();
      // ...
      // Do UI stuff to allow the user to pick a device
      m_device = myUI.getSelectedDevice();
      // ...
   }

To be informed of location changes, an application must implement the Location listener interface, then register for location updates;

import android.location.LocationListener;

public MyClass implements LocationListener
{
    public void onLocationChanged(Location location)
   {
      /* Do something useful */
   }

   // ...
   m_locationManager.requestLocationUpdates( m_device, 
                                             GPS_MINIMUM_TIME, 
                                             GPS_MINIMUM_DISTANCE, 
                                             this );
   // ...
}

When the Location provider device has a new location for the application, the location manager will call this method. Because the listener method onLocationChanged will be called by another LocationProvider thread, the application must not use much CPU time. The application must use proper thread synchronization and notification techniques to pass the location object to the working parts of the Application.

The application is mostly isolated from the details of the actual devices being used, except for a couple of areas. The Location object, a normalized location in terms of Lat/Lon/Altitude, may contain device specific information. Currently the LocationManager defines extensions for Northing/Easting, and extended status information may be passed back. All extended information is returned in the Location object as “Extras”.

Applications may record streams of locations using the following methods:

   public void record( OutputStream strm, String comment )
      throws IOException

Typically the output stream is sent to persistent storage, but any legal stream is acceptable, provided it has enough space for the recording. The output of the stream is an extended GPX format file. The extensions provide the ability to include Northing/Easting, and other AGTEK unique data to the location stream. Call stopRecord to complete the recording stream.

Applications may playback the location stream using the PlaybackDevice/PlaybackProvider. These function exactly the same as a normal LocationManager capable instrument. The PlaybackProvider will send updates back to the application at exactly the same rate as they were recorded.

The LocationManager is still relatively early in its development, so changes are to be expected. In particular areas of device initialization/startup and reporting status to applications are not well developed. These are expected to mature as new devices are added to the framework.

It is beyond the scope of this short introduction to detail each an every method on objects within the LocationManager framework. The best way to understand individual methods is to read the JavaDocs for the Lib and package com.agtek.location.

Interested readers are directed to the Location Manager Architecture page for detailed implementation information.