fixup docs and cleanup

Author: thomaszurkan-optimizely

datafile-handler/src/main/AndroidManifest.xml

@@ -29,7 +29,8 @@
         </service>
         <!--
           Add these lines to your manifest if you want the services to schedule themselves again after a boot
-          or package replace.
+          or package replace.  Without these lines in your application manifest, the DatafileRescheduler will not be used.
+          See {link test_app} AndroidManifest.xml as an example.
 
                 <receiver
                     android:name="DatafileRescheduler"

datafile-handler/src/main/java/com/optimizely/ab/android/datafile_handler/BackgroundWatchersCache.java

@@ -16,6 +16,7 @@
 
 package com.optimizely.ab.android.datafile_handler;
 
+import android.content.Context;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 
@@ -31,17 +32,33 @@
 
 /**
  * Caches a json dict that saves state about which project IDs have background watching enabled.
+ * This is used by the rescheduler to determine if backgrounding was on for a project id.  If backgrounding is on,
+ * then when the device is restarted or the app is reinstalled, the rescheduler will kick in and reschedule the datafile background
+ * download.  In order to use this the rescheduler needs to be included in the application manifest.
+ * Calling {@link DatafileHandler#stopBackgroundUpdates(Context, String)} sets this background cache to false.
  */
 class BackgroundWatchersCache {
     static final String BACKGROUND_WATCHERS_FILE_NAME = "optly-background-watchers.json";
     @NonNull private final Cache cache;
     @NonNull private final Logger logger;
 
+    /**
+     * Create BackgroundWatchersCache Object.
+     *
+     * @param cache object for caching project id and whether watched or not.
+     * @param logger the logger to log errors and warnings.
+     */
     BackgroundWatchersCache(@NonNull Cache cache, @NonNull Logger logger) {
         this.cache = cache;
         this.logger = logger;
     }
 
+    /**
+     * Set the watching flag for the proejct id.
+     * @param projectId project id to set watching.
+     * @param watching flag to signify if the project is running in the background.
+     * @return boolean indicating whether the set succeed or not
+     */
     boolean setIsWatching(@NonNull String projectId, boolean watching) {
         if (projectId.isEmpty()) {
             logger.error("Passed in an empty string for projectId");
@@ -61,6 +78,11 @@ boolean setIsWatching(@NonNull String projectId, boolean watching) {
         return false;
     }
 
+    /**
+     * Return if the project is set to be watched in the background or not.
+     * @param projectId project id to test
+     * @return true if it has backgrounding, false if not.
+     */
     boolean isWatching(@NonNull String projectId) {
         if (projectId.isEmpty()) {
             logger.error("Passed in an empty string for projectId");
@@ -81,6 +103,10 @@ boolean isWatching(@NonNull String projectId) {
         return false;
     }
 
+    /**
+     * Get a list of all project ids that are being watched for backgrounding.
+     * @return a list of project ids
+     */
     List<String> getWatchingProjectIds() {
         List<String> projectIds = new ArrayList<>();
         try {
@@ -101,6 +127,11 @@ List<String> getWatchingProjectIds() {
         return projectIds;
     }
 
+    /**
+     * Load the JSONObject from cache
+     * @return JSONObject if successful. JSONObject can be empty
+     * @throws JSONException if there was a problem parsing the JSON
+     */
     @Nullable
     private JSONObject load() throws JSONException {
         String backGroundWatchersFile = cache.load(BACKGROUND_WATCHERS_FILE_NAME);
@@ -112,10 +143,19 @@ private JSONObject load() throws JSONException {
         return new JSONObject(backGroundWatchersFile);
     }
 
+    /**
+     * Delete the background watchers cache file.
+     * @return true if successful and false if it failed.
+     */
     protected boolean delete() {
         return cache.delete(BACKGROUND_WATCHERS_FILE_NAME);
     }
 
+    /**
+     * Save the JSON string to the background cache file.
+     * @param backgroundWatchersJson JSON string containing projectid and whether watched or not.
+     * @return true if successful.
+     */
     private boolean save(String backgroundWatchersJson) {
         logger.info("Saving background watchers file {}.", BACKGROUND_WATCHERS_FILE_NAME);
         boolean saved = cache.save(BACKGROUND_WATCHERS_FILE_NAME, backgroundWatchersJson);

datafile-handler/src/main/java/com/optimizely/ab/android/datafile_handler/DatafileCache.java

@@ -27,7 +27,7 @@
 import org.slf4j.Logger;
 
 /**
- * Abstracts the actual data "file" {@link java.io.File}.
+ * Abstracts the actual data "file" {@link java.io.File}. to a cached file
  */
 public class DatafileCache {
 
@@ -37,25 +37,47 @@ public class DatafileCache {
     @NonNull private final String filename;
     @NonNull private final Logger logger;
 
+    /**
+     * Create a DatafileCache Object
+     * @param projectId project id for cache
+     * @param cache shared generic file based {link Cache}
+     * @param logger logger to use
+     */
     public DatafileCache(@NonNull String projectId, @NonNull Cache cache, @NonNull Logger logger) {
         this.cache = cache;
         this.filename = String.format(FILENAME, projectId);
         this.logger = logger;
     }
 
+    /**
+     * Delete the datafile cache
+     * @return true if successful
+     */
     public boolean delete() {
         return cache.delete(filename);
     }
 
+    /**
+     * Check to see if the datafile cache exists
+     * @return true if it exists
+     */
     public boolean exists() {
         return cache.exists(filename);
     }
 
+    /**
+     * Return the filename to the datafile cache
+     * @return filename for datafile cache
+     */
     @VisibleForTesting
     public String getFileName() {
         return filename;
     }
 
+    /**
+     * Loads the datafile from cache into a JSONObject
+     * @return JSONObject if exists or nulll if it doesn't or there was a problem
+     */
     @Nullable
     public JSONObject load() {
         String datafile = cache.load(filename);
@@ -71,6 +93,11 @@ public JSONObject load() {
         }
     }
 
+    /**
+     * Save a datafile to cache.
+     * @param dataFile to write to cache
+     * @return true if successful.
+     */
     public boolean save(String dataFile) {
         return cache.save(filename, dataFile);
     }

datafile-handler/src/main/java/com/optimizely/ab/android/datafile_handler/DatafileClient.java

@@ -35,6 +35,11 @@ public class DatafileClient {
     @NonNull private final Client client;
     @NonNull private final Logger logger;
 
+    /**
+     * Create a DatafileClient Object.
+     * @param client Shared {@link Client} object
+     * @param logger logger for logging.
+     */
     public DatafileClient(@NonNull Client client, @NonNull Logger logger) {
         this.client = client;
         this.logger = logger;

datafile-handler/src/main/java/com/optimizely/ab/android/datafile_handler/DatafileRescheduler.java

@@ -31,8 +31,22 @@
 /**
  * Broadcast Receiver that handles app upgrade and phone restart broadcasts in order
  * to reschedule {@link DatafileService}
+ * In order to use this class you must include the declaration in your AndroidManifest.xml.
+ * <pre>
+ * {@code
+ * <receiver
+ *  android:name="DatafileRescheduler"
+ *  android:enabled="true"
+ *  android:exported="false">
+ *  <intent-filter>
+ *      <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+ *      <action android:name="android.intent.action.BOOT_COMPLETED" />
+ *  </intent-filter>
+ * </receiver>
+ * }
+ * </pre>
  *
- * @hide
+ * as well as set the download interval for datafile download in the Optimizely builder.
  */
 public class DatafileRescheduler extends BroadcastReceiver {
     Logger logger = LoggerFactory.getLogger(DatafileRescheduler.class);

datafile-handler/src/main/java/com/optimizely/ab/android/datafile_handler/DatafileService.java

@@ -35,8 +35,8 @@
 
 /**
  * Service that handles loading the datafile from cache or downloads it from the CDN
- *
- * @hide
+ * These services will only be used if you are using our {@link DefaultDatafileHandler}.
+ * You can chose to implement your own handler and use all or part of this package.
  */
 public class DatafileService extends Service {
     /**

datafile-handler/src/main/java/com/optimizely/ab/android/datafile_handler/DatafileServiceConnection.java

@@ -32,6 +32,10 @@
 
 import java.util.concurrent.Executors;
 
+/**
+ * The DatafileServiceConnection is used to bind to a DatafileService.  The DatafileService does that actual download.
+ * The Service Connection kicks off the service after being connected.  The connection is unbound after a successful download.
+ */
 public class DatafileServiceConnection implements ServiceConnection {
 
     @NonNull private final Context context;
@@ -40,14 +44,21 @@ public class DatafileServiceConnection implements ServiceConnection {
 
     private boolean bound = false;
 
+    /**
+     * Create a datafile service connection object.
+     * @param projectId project id for service
+     * @param context current application context.
+     * @param listener listener to call after service download has completed.
+     */
     public DatafileServiceConnection(@NonNull String projectId, @NonNull Context context, @NonNull DatafileLoadedListener listener) {
         this.projectId = projectId;
         this.context = context;
         this.listener = listener;
     }
 
     /**
-     * @hide
+     * Get the bound {@link DatafileService} and set it up for download.
+     *
      * @see ServiceConnection#onServiceConnected(ComponentName, IBinder)
      */
     @RequiresApi(api = Build.VERSION_CODES.HONEYCOMB)
@@ -84,7 +95,7 @@ public void onServiceConnected(ComponentName className,
     }
 
     /**
-     * @hide
+     * Call stop on the listener after the service has been disconnected.
      * @see ServiceConnection#onServiceDisconnected(ComponentName)
      */
     @Override
@@ -93,10 +104,18 @@ public void onServiceDisconnected(ComponentName arg0) {
        listener.onStop(context);
     }
 
+    /**
+     * Is the service bound?
+     * @return true if it is bound.
+     */
     public boolean isBound() {
         return bound;
     }
 
+    /**
+     * Set whether the service is bound or not.
+     * @param bound boolean flag.
+     */
     public void setBound(Boolean bound) {
         this.bound = bound;
     }

event-handler/src/main/java/com/optimizely/ab/android/event_handler/DefaultEventHandler.java

@@ -29,7 +29,8 @@
 /**
  * Reference implementation of {@link EventHandler} for Android.
  * <p>
- * This is the main entry point to the Android Module
+ * This is the main entry point to the Android Module.  This event handler creates a service intent and starts it in the passed
+ * in context.  The intent service will attempt to send any and all queued events.
  */
 public class DefaultEventHandler implements EventHandler {
 
@@ -38,6 +39,10 @@ public class DefaultEventHandler implements EventHandler {
     Logger logger = LoggerFactory.getLogger(DefaultEventHandler.class);
     private long dispatchInterval = -1;
 
+    /**
+     * Private constructor
+     * @param context current context for service.
+     */
     private DefaultEventHandler(@NonNull Context context) {
         this.context = context;
     }

event-handler/src/main/java/com/optimizely/ab/android/event_handler/EventClient.java

@@ -39,6 +39,11 @@ class EventClient {
         this.logger = logger;
     }
 
+    /**
+     * Attempt to send the event to the event url.
+     * @param event to send
+     * @return true if successful
+     */
     boolean sendEvent(final Event event) {
         Client.Request<Boolean> request = new Client.Request<Boolean>() {
             @Override

event-handler/src/main/java/com/optimizely/ab/android/event_handler/EventDAO.java

@@ -34,24 +34,43 @@
 
 /**
  * Handles interactions with the SQLiteDatabase that store {@link Event} instances.
+ * This is the event queue for Android.
  */
 class EventDAO {
 
     @NonNull
     final Logger logger;
     @NonNull private final EventSQLiteOpenHelper dbHelper;
 
+    /**
+     * Private constructor
+     *
+     * @param dbHelper helper for SQLite calls.
+     * @param logger where to log errors and warnings.
+     */
     private EventDAO(@NonNull EventSQLiteOpenHelper dbHelper, @NonNull Logger logger) {
         this.dbHelper = dbHelper;
         this.logger = logger;
     }
 
+    /**
+     * Static initializer for EventDAO.
+     * @param context current context
+     * @param projectId current project id
+     * @param logger where to log errors and warnings.
+     * @return a new instance of EventDAO.
+     */
     @RequiresApi(api = Build.VERSION_CODES.HONEYCOMB)
     static EventDAO getInstance(@NonNull Context context, @NonNull String projectId, @NonNull Logger logger) {
         EventSQLiteOpenHelper sqLiteOpenHelper = new EventSQLiteOpenHelper(context, projectId, null, EventSQLiteOpenHelper.VERSION, LoggerFactory.getLogger(EventSQLiteOpenHelper.class));
         return new EventDAO(sqLiteOpenHelper, logger);
     }
 
+    /**
+     * Store an event in SQLite
+     * @param event to store
+     * @return true if successful
+     */
     boolean storeEvent(@NonNull Event event) {
         logger.info("Inserting {} into db", event);
         ContentValues values = new ContentValues();
@@ -74,6 +93,10 @@ boolean storeEvent(@NonNull Event event) {
         return false;
     }
 
+    /**
+     * Get all the events in the SQLite queue
+     * @return a list of events.
+     */
     List<Pair<Long, Event>> getEvents() {
         List<Pair<Long, Event>> events = new LinkedList<>();
 
@@ -139,6 +162,11 @@ List<Pair<Long, Event>> getEvents() {
         return events;
     }
 
+    /**
+     * Remove an event from SQLite db.
+     * @param eventId id of the event to remove
+     * @return true on success.
+     */
     boolean removeEvent(long eventId) {
         // Define 'where' part of query.
         String selection = EventTable._ID + " = ?";
@@ -164,6 +192,9 @@ boolean removeEvent(long eventId) {
         return false;
     }
 
+    /**
+     * Close the SQLite DB.
+     */
     void closeDb() {
         try {
             dbHelper.close();