Class Usage
-
- 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
2. UsageRecord-- Represents a single unit of usage information reported by a// Instantiates your UsageStore implementation, for example: MyUsageStore store = new MyUsageStore("myStoreDatabaseName"); Usage usage = new Usage(store);
, 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 anUsageReporter
instance. Extending UsageRecord:Enum
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 generatepublic 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 }
which is stored in an implementation ofUsageRecord
. Reporting Usage Events:UsageStore
4. UsageSnapshot A snapshot object is created via// 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);
and is used by the Usage Uploader when uploading usage data to the remote server. It contains a collection ofUsageStore.getSnapshot(androidContext, targetID)
reported by aUsageRecords
, 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:UsageReporter
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,// This is usually done when uploading usage records. UsageSnapshot snapshot = usage.getStore().getSnapshot(androidContext, myTargetID);
// 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. ... }
-
-
Constructor Summary
Constructors Constructor Description Usage(UsageStore usageStore)
Constructs an Usage
instance by providing an instance of UsageStore implementation.
-
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. -
-
Constructor Detail
-
Usage
Usage(UsageStore usageStore)
Constructs anUsage
instance by providing an instance of UsageStore implementation.- Parameters:
usageStore
- an instance of a concrete implementation ofUsageStore
-
-
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.
-
-
-
-