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
    :
    
        // 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.
        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.