All Implemented Interfaces:


public class Usage

This class serves as the entry point to a set of framework APIs that allow you to extend and implement your own usage reporting based on your own server, to collect, store, and upload client usage events in a flexible way.

1. Initialization Usage-- Need to implement UsageStore before you can instantiate the
   Usage:

    // Instantiates your UsageStore implementation, for example:
    MyUsageStore store = new MyUsageStore("myStoreDatabaseName");
    Usage usage = new Usage(store);


2. UsageRecord-- Represents a single unit of usage information reported by a
   UsageReporter, which contains:
   a. Date-- The date when the UsageRecord is reported and persisted.
   b. UsageInfo Object-- Contains server specific event details as name-value pairs
      saved in a HashMap<String, String>.
   c. User-defined event type implemented as an Enum instance.

   Extending UsageRecord:

        public class MyUsageRecord extends UsageRecord<MyUsageRecord.MyEvent> {
            // Constructor-- Constructs a usage record with one of my event type and a date.
            MyUsageRecord(MyEvent event, Date date, UsageInfo info) {
                super(event, date, info);
                logger.debug("Instantiated Usage Record: Event[{}], Date: {}", event, date);
            }
        }

        // User-defined event types.
        enum MyEvent {
            EVENT1, EVENT2, EVENT3, EVENT4, EVENT5
        }


3. UsageReporter
   A target is a logical group of collected events and information, collected for a specific
   purpose, and sent to a given analytics server.
   All events are reported using a reporter assigned with a target ID. The reporter’s only task is
   to generate UsageRecord which is stored in an implementation of
   UsageStore.

   Reporting Usage Events:

        // 1. Instantiates a reporter by specifying the target ID and the store.
        UsageReporter reporter = new UsageReporter(myTargetID, usage.getStore());

        // 2. Registers and enables the reporter.
        usage.registerReporter(reporter);

        // 3. Creates a usage record with user-defined event type.

        //    a. Initiates a UsageInfo with a HashMap, then fills it with implementation
        //       specific name-value pairs.
        UsageInfo info = new UsageInfo(new HashMap<String, String>());
        info.setValue("Screen", "Property Screen")
            .setValue("DeviceId", "1235")
            .setValue("InfoCategory", "UI");

        //    b. Instantiates a usage record with an event type, date, and UsageInfo object.
        MyUsageRecord record = new MyUsageRecord(MyUsageRecord.MyEvent.EVENT1, new Date(), info);

        // 4. Reports usage, the record will be persisted in the usage store.
        reporter.reports(record);


4. UsageSnapshot
   A snapshot object is created via UsageStore.getSnapshot(androidContext, targetID)
   and is used by the Usage Uploader when uploading usage data to the remote server.

   It contains a collection of UsageRecords
 reported by a UsageReporter,
   grouped under a Target ID, and persisted in a UsageStore.

   The records collected in a snapshot is using the creation date of the snapshot as the cut-off
   date, that is, all UsageRecords reported before the cut-off date will be included in the
   snapshot.

5. UsageStore--
   a. An interface that manages the storing, retrieval, and deletion of UsageRecords.
   b. Used by the Usage Uploader to take a snapshot of records associated with a target ID.

   Generating a Snapshot:

        // This is usually done when uploading usage records.
        UsageSnapshot snapshot = usage.getStore().getSnapshot(androidContext, myTargetID);


6. Usage Uploader-- Based on your server's protocol and data format, the implementation should
   follow the steps below:
   a. Takes a Usage Snapshot.
   b. Transforms each Usage Record in the snapshot to the data format required by the server.
   c. Uploads the data to a given server.
   d. Removes Usage Records in the snapshot from the Usage Store upon success upload.

   For example,

        // In the uploader's upload implementation:

        // Uses try-with statement, which will invoke snapshot.close() at the end.
        try (
            // 1. Takes a snapshot from the instance of your UsageStore implementation.
            MyUsageSnapshotImpl snapshot = usage.getStore().getSnapshot(androidContext, myTargetID);
        ) {
            // 2. Iterates through the usage records in the snapshot.
            while (snapshot.hasNext()) {
                MyUsageRecord record = snapshot.next();
                ...
                // 3. Converts the record to the format required by your server.
                ...
            }

            // 4. Uploads to the server.
            ...
            // 5. If the upload is successful, removes the records in the snapshot.
            snapshot.removeRecords();
        } catch (SomeException ex) {
            // Error handling.
            ...
        }

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description

Field Summary

Fields
Modifier and Type	Field	Description

Constructor Summary

Constructors
Constructor	Description
`Usage(UsageStore usageStore)`	Constructs an `Usage` instance by providing an instance of UsageStore implementation.

Enum Constant Summary

Enum Constants
Enum Constant	Description

Method Summary

Modifier and Type	Method	Description
`UsageStore`	`getStore()`	Returns the embedded Usage Store implementation.
`synchronized UsageReporter`	`getReporter(@NonNull() String targetId)`	Returns a Usage Reporter with the given target ID.
`synchronized void`	`registerReporter(@NonNull() UsageReporter reporter)`	Registers and enables the given Usage Reporter.
`synchronized void`	`unregisterReporter(@NonNull() String targetId)`	Unregisters the previously registered custom UsageReporter.
`synchronized Array<String>`	`getTargetIdentifiers()`	Retrieves the available target identifiers.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Usage
```
Usage(UsageStore usageStore)
```
    Constructs an Usage instance by providing an instance of UsageStore implementation.
    Note that the store must have been initialized properly and ready to perform database CRUD operations.
    
    Parameters:
    
    usageStore - an instance of a concrete implementation of UsageStore
- Method Detail
  - getStore
```
@NonNull() UsageStore getStore()
```
    Returns the embedded Usage Store implementation.
    
    Returns:
    
    The embedded Usage Store implementation.
  - getReporter
```
@NonNull() synchronized UsageReporter getReporter(@NonNull() String targetId)
```
    Returns a Usage Reporter with the given target ID. If the usage reporter never explicitly registered via registerReporter, a new Usage Reporter will be created and enabled, same effect as if the user has called registerReporter.
    
    Parameters:
    
    targetId - target ID of the Usage Reporter
    
    Returns:
    
    A usage reporter for the given target ID.
  - registerReporter
```
 synchronized void registerReporter(@NonNull() UsageReporter reporter)
```
    Registers and enables the given Usage Reporter. Used for registering custom UsageReporter that subclassed from UsageReporter.
    
    Parameters:
    
    reporter - a usage reporter
  - unregisterReporter
```
 synchronized void unregisterReporter(@NonNull() String targetId)
```
    Unregisters the previously registered custom UsageReporter. After un-registering a reporter it can no longer report to the usage store and must be re-registered to use again.
    
    Parameters:
    
    targetId - a non-null target identifier associated with the UsageReporter that was previously registered via registerReporter
  - getTargetIdentifiers
```
@NonNull() synchronized Array<String> getTargetIdentifiers()
```
    Retrieves the available target identifiers. This includes all the persisted and non-persisted reporters.
    
    Returns:
    
    An non-null array of target IDs, the array may be empty.

Class Usage

Nested Class Summary

Field Summary

Constructor Summary

Enum Constant Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Usage

Method Detail

getStore

getReporter

registerReporter

unregisterReporter

getTargetIdentifiers