Merge pull request #45 from optimizely/elliot/notification3

Notification listeners

Author: elliotykim

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Change `UserExperimentRecord` to `UserProfile`
 - Add support for IP anonymization
+- Add `NotificationListener` for SDK events
 
 ## 1.1.0
 

core-api/src/main/java/com/optimizely/ab/Optimizely.java

@@ -39,6 +39,8 @@
 import com.optimizely.ab.event.internal.EventBuilderV2;
 import com.optimizely.ab.event.internal.payload.Event.ClientEngine;
 import com.optimizely.ab.internal.ProjectValidationUtils;
+import com.optimizely.ab.notification.NotificationListener;
+import com.optimizely.ab.notification.NotificationBroadcaster;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -89,6 +91,7 @@ public class Optimizely {
     @VisibleForTesting final ProjectConfig projectConfig;
     @VisibleForTesting final EventHandler eventHandler;
     @VisibleForTesting final ErrorHandler errorHandler;
+    @VisibleForTesting final NotificationBroadcaster notificationBroadcaster = new NotificationBroadcaster();
 
     private Optimizely(@Nonnull ProjectConfig projectConfig,
                        @Nonnull Bucketer bucketer,
@@ -180,6 +183,8 @@ private Optimizely(@Nonnull ProjectConfig projectConfig,
             logger.error("Unexpected exception in event dispatcher", e);
         }
 
+        notificationBroadcaster.broadcastExperimentActivated(experiment, userId, attributes, variation);
+
         return variation;
     }
 
@@ -438,6 +443,33 @@ private static ProjectConfig getProjectConfig(String datafile) throws ConfigPars
         return DefaultConfigParser.getInstance().parseProjectConfig(datafile);
     }
 
+    //======== Notification listeners ========//
+
+    /**
+     * Add a {@link NotificationListener} if it does not exist already.
+     *
+     * @param listener listener to add
+     */
+    public void addNotificationListener(@Nonnull NotificationListener listener) {
+        notificationBroadcaster.addListener(listener);
+    }
+
+    /**
+     * Remove a {@link NotificationListener} if it exists.
+     *
+     * @param listener listener to remove
+     */
+    public void removeNotificationListener(@Nonnull NotificationListener listener) {
+        notificationBroadcaster.removeListener(listener);
+    }
+
+    /**
+     * Remove all {@link NotificationListener}.
+     */
+    public void clearNotificationListeners() {
+        notificationBroadcaster.clearListeners();
+    }
+
     //======== Helper methods ========//
 
     /**

core-api/src/main/java/com/optimizely/ab/event/internal/EventBuilderV2.java

@@ -209,4 +209,4 @@ private List<LayerState> createLayerStates(ProjectConfig projectConfig, Bucketer
 
         return layerStates;
     }
-}
+}

core-api/src/main/java/com/optimizely/ab/notification/NotificationBroadcaster.java

@@ -0,0 +1,95 @@
+/**
+ *
+ *    Copyright 2016, Optimizely
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package com.optimizely.ab.notification;
+
+import com.optimizely.ab.annotations.VisibleForTesting;
+import com.optimizely.ab.config.Experiment;
+import com.optimizely.ab.config.Variation;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.HashSet;
+import java.util.Map;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Manages Optimizely SDK notification listeners and broadcasts messages.
+ */
+public class NotificationBroadcaster {
+
+    private static final Logger logger = LoggerFactory.getLogger(NotificationBroadcaster.class);
+
+    @VisibleForTesting final HashSet<NotificationListener> listeners =
+            new HashSet<NotificationListener>();
+
+    /**
+     * Add a listener if it does not exist already.
+     *
+     * @param listener listener to add
+     */
+    public void addListener(@Nonnull NotificationListener listener) {
+        if (listeners.contains(listener)) {
+            logger.debug("Notification listener was not added because it already existed");
+            return;
+        }
+
+        listeners.add(listener);
+        logger.debug("Notification listener was added");
+    }
+
+    /**
+     * Remove a listener if it exists.
+     *
+     * @param listener listener to remove
+     */
+    public void removeListener(@Nonnull NotificationListener listener) {
+        if (listeners.contains(listener)) {
+            listeners.remove(listener);
+            logger.debug("Notification listener was removed");
+            return;
+        }
+
+        logger.debug("Notification listener was not removed because it did not exist");
+    }
+
+    /**
+     * Remove all listeners.
+     */
+    public void clearListeners() {
+        listeners.clear();
+        logger.debug("Notification listeners were cleared");
+    }
+
+    /**
+     * Notify listeners that an Optimizely experiment has been activated.
+     *
+     * @param experiment the key of the activated experiment
+     * @param userId the id of the user
+     * @param attributes a map of attributes about the user
+     * @param variation the key of the variation that was bucketed
+     */
+    public void broadcastExperimentActivated(@Nonnull Experiment experiment,
+                                             @Nonnull String userId,
+                                             @Nonnull Map<String, String> attributes,
+                                             @Nonnull Variation variation) {
+        for (final NotificationListener iterListener : listeners) {
+            iterListener.onExperimentActivated(experiment, userId, attributes, variation);
+        }
+    }
+}

core-api/src/main/java/com/optimizely/ab/notification/NotificationListener.java

@@ -0,0 +1,50 @@
+/**
+ *
+ *    Copyright 2016, Optimizely
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package com.optimizely.ab.notification;
+
+import com.optimizely.ab.config.Experiment;
+import com.optimizely.ab.config.Variation;
+
+import java.util.Map;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Abstract class for Optimizely notification listeners.
+ * <p>
+ * We use an abstract class here instead of an interface for convenience of use and backwards
+ * compatibility in the future. An interface would force consumers to implement every method defined
+ * on it as well as update their application code with new method implementations every time new
+ * methods are added to the interface in the SDK. An abstract classes allows consumers to override
+ * just the methods they need.
+ */
+public abstract class NotificationListener {
+
+    /**
+     * Listener that is called after an experiment has been activated.
+     *
+     * @param experiment the activated experiment
+     * @param userId the id of the user
+     * @param attributes a map of attributes about the user
+     * @param variation the key of the variation that was bucketed
+     */
+    public void onExperimentActivated(@Nonnull Experiment experiment,
+                                      @Nonnull String userId,
+                                      @Nonnull Map<String, String> attributes,
+                                      @Nonnull Variation variation) {
+    }
+}