GPS Extractors

Introduction

The GPS extractors allow you to monitor the location of the client. There are two GPS extractors available in the framework. The first extractor works periodically with a configurable period, and the second extractor works whenever the GPS sensor of the client gets an updated reading. These both use the GPS sensor on the phone to indicate the current latitude and longitude of the phone, or last known if signal has been lost.

This tutorial will briefly show the functionality of tracking location data using each type of GPS extractor, including the encapsulator used and the basics of recording datapoints into it. Finally we will show a full example of usage with the periodic extractor.

Prerequisites

The prerequisites that the platform will check for the two types of GPS extractors is that the phone has GPS capability in hardware, that this capability is currently enabled by the user, and that the permissions to use GPS are included in the manifest (described below). If any of these requirements is not met, the reqSatisfied() function will throw an ExtractorPrerequisiteUnsatisfiedException . In this case, the extractor will not start and the extractor will not become active. Otherwise, the method will return void  and the extractor will start.

We can check if the requirements have been satisfied by a try-catch statement:

try {
    periodicGPSExt.reqSatisfied();
    periodicGPSExt.start();
} catch (ExtractorPrerequisiteUnsatisfiedException e) {
    // The prerequisites of the GPS extractor are not satisfied
}

// Keep collecting until...
periodicGPSExt.terminate();

Permission to use GPS must be specified in the AndroidManifest.xml file of the client application by adding the following line:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Periodic GPS Extractor

The periodic GPS extractor will try to obtain a location datapoint at the specified period, and add the point to the encapsulator specified upon instantiation, and if signal cannot be obtained either the last known location will be repeated if available, or no datapoint will be added. The periodic extractor is instantiated as follows:

int period = 60 * 1000; // 1 minute
DataJobIdentifier gpsJobId = new DataJobIdentifier("GPS");
BackableEncapsulator<TimeZonedTimestampedObject<GPSLatLongContainer>> gpsData = new BackableEncapsulator<TimeZonedTimestampedObject<GPSLatLongContainer>>(gpsJobId);
periodicGPSExt = new GPSLatLongExtractor(gpsData, period, this.getApplicationContext());

As described in the extractors and estimators page, a listener can be added to trigger whenever a new datapoint is obtained and add it to the encapsulator:

gpsData.addListener(new SendDataAtFullListener());

Thus data will be obtained periodically and sent to the encapsulator.

Event-Based GPS Extractor

Instantiation and usage of the event-based GPS extractor is very similar to that of the periodic extractor, with only the slight difference that the developer can specify a granularity in terms of minimum distance to trigger a location update and minimum time between updates. The extractor will only obtain a new data point when the GPS location varies by this level of granularity, rather than obtaining a data point at a fixed period. It is written to trigger collection on the Android’s built-in onLocationChanged callback. The event-based extractor is instantiated as follows:

long minDistance = 10; // 10 meters
long minTime = 60 * 1000; // 1 minute
DataJobIdentifier gpsJobId = new DataJobIdentifier("GPS");
BackableEncapsulator<TimeZonedTimestampedObject<GPSLatLongContainer>> gpsData = new BackableEncapsulator<TimeZonedTimestampedObject<GPSLatLongContainer>>(gpsJobId);
eventBasedGPSExt = new GPSLatLongExtractorEventBased(gpsData, minDistance, minTime, this.getApplicationContext());

The listener is added to the encapsulator in exactly the same way as for the periodic extractor:

gpsData.addListener(new SendDataAtFullListener());

Running Example

(TODO: complete)