Battery Usage Extractor


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:

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 :

Finally, the extractor must be started:

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 its terminate() method:

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:

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 :

Finally, the extractor must be started:

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:

Running Example

(TODO: complete)