Battery Usage Extractor

Table of Contents

Introduction

The battery usage extractor allows you to monitor the battery usage of the client node. This includes information on

  • whether the battery is charging,
  • whether the battery is charging via USB,
  • whether the battery is charging via AC,
  • and percentage of charge remaining.

There are two battery usage extractors available in the framework. The first extractor works periodically with a configurable period, and the second extractor works whenever battery level changes at a configurable level of granularity.

In this tutorial, we will demonstrate how to initialize and use each of these two types of extractors.

Prerequisites

The only prerequisite for both battery usage extractors is the presence of an attached battery on the client node. However, we make the assumption that the android device has a battery. The extractor’s reqSatisfied() method never through an exception, and the extractor will always start. General information about the reqSatisfied() method can be found in the extractors and estimators page.

Periodic battery usage extractor

The periodic battery usage extractor collects information about the battery at regular time intervals. The period if these intervals can be configured.

How to initialize the periodic battery usage extractor

First, the BackableEncapsulator used to store the battery usage data must be instantiated and registered with a listener. To do this, first configure a period and create a BackableEncapsulator:

int period = 6000; // 1 minute in milliseconds

DataJobIdentifier batteryJobId = new DataJobIdentifier("Battery");
BackableEncapsulator<TimeZonedTimestampedObject<BatteryUsageContainer>> batteryData = new BackableEncapsulator<TimeZonedTimestampedObject<BatteryUsageContainer>>(batteryJobId);
batteryData.addListener(new SendDataAtFullListener());

In this particular example, the period is set to 1 minute, and the BackableEncapsulator stores the battery usage data as a TimeZonedTimestampedObject that contains a BatteryUsageContainer. Check the backable encapsulator page for details. (todo: discuss containers?)

Now, the extractor can be instantiated using the configured period and BackableEncapsulator :

BatteryUsageExtractor batteryExt = new BatteryUsageExtractor(batteryData, period, this.getApplicationContext());

Finally, the extractor must be started:

// The check will always pass, so the extractor will always start when it gets here
try {
    batteryExt.reqSatisfied();
    batteryExt.start();
} catch (ExtractorPrerequisiteUnsatisfiedException e) {
    // The prerequisites of this extractor were not met
}

Note that in order to start the extractor, its prerequisites must be satisfied. This is done by calling the reqSatisfied() method in a try-catch block because the method will throw an ExtractorPrerequisiteUnsatisfiedException  if the prerequisites of the extractor weren’t met instead of returning void . In case you decide to change the behavior of the extractor by changing it’s prerequisites, we include the try-catch statement.

After starting successfully, the BackableEncapsulator containing the battery data will be periodically updated.

How to terminate the periodic battery usage extractor

If you no longer need to battery usage extractor to run, you can simply call itsterminate() method:

batteryExt.terminate();

Event-based battery usage extractor

The event-based battery usage extractor collects information about the battery whenever its charge level changes. The amount of this change can be configured.

How to initialize the event-based battery usage extractor

First, the BackableEncapsulator used to store the battery usage data must be instantiated and registered with a listener. To do this, first configure a battery percent change and create a BackableEncapsulator:

double pctChange = 5; // 5 percent change in battery charge level

DataJobIdentifier batteryJobId = new DataJobIdentifier("Battery");
BackableEncapsulator<TimeZonedTimestampedObject<BatteryUsageContainer>> batteryData = new BackableEncapsulator<TimeZonedTimestampedObject<BatteryUsageContainer>>(batteryJobId);
batteryData.addListener(new SendDataAtFullListener());

In this particular example, the percent change is set to 5% of the battery level, and the BackableEncapsulator stores the battery usage data as a TimeZonedTimestampedObject that contains a BatteryUsageContainer. Check the backable encapsulator page for details. (todo: discuss containers?)

Now, the extractor can be instantiated using the configured percent change and BackableEncapsulator :

BatteryUsageExtractorEventBased batteryExt = new BatteryUsageExtractorEventBased(batteryData, pctChange, this.getApplicationContext());

Finally, the extractor must be started:

try {
    batteryExt.reqSatisfied();
    batteryExt.start();
} catch (ExtractorPrerequisiteUnsatisfiedException e) {
    // The prerequisites of this extractor were not met
}

Note that in order to start the extractor, its prerequisites must be satisfied. However, we assume that the android device includes a battery, so the extractor will always start.

After starting successfully, the BackableEncapsulator containing the battery data will be updated whenever the level changes by .

How to terminate the periodic battery usage extractor

If you no longer need to battery usage extractor to run, you can simply call its terminate() method:

batteryExt.terminate();

Running Example

(TODO: complete)