Feature/bucketing (#154)

* bucketing id implementation
* add a few more unit tests
* change bucket name
* added event builder code and tests after looking at php master bucketing_id changes
* cleanup from alda's comments
* update bucketingId javadoc and tests
* remove userId from bucketer method parameters since it is only used for logging
* update to fix FindBug warnings

Author: thomaszurkan-optimizely

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

@@ -667,7 +667,8 @@ private LiveVariable getLiveVariableOrThrow(ProjectConfig projectConfig, String
      * {@link ProjectConfig}.
      *
      * @param projectConfig the current project config
-     * @param attributes the attributes map to validate and potentially filter
+     * @param attributes the attributes map to validate and potentially filter. The reserved key for bucketing id
+     * {@link DecisionService#BUCKETING_ATTRIBUTE} is kept.
      * @return the filtered attributes map (containing only attributes that are present in the project config) or an
      * empty map if a null attributes object is passed in
      */
@@ -682,7 +683,8 @@ private Map<String, String> filterAttributes(@Nonnull ProjectConfig projectConfi
 
         Map<String, Attribute> attributeKeyMapping = projectConfig.getAttributeKeyMapping();
         for (Map.Entry<String, String> attribute : attributes.entrySet()) {
-            if (!attributeKeyMapping.containsKey(attribute.getKey())) {
+            if (!attributeKeyMapping.containsKey(attribute.getKey()) &&
+                    attribute.getKey() != com.optimizely.ab.bucketing.DecisionService.BUCKETING_ATTRIBUTE) {
                 if (unknownAttributes == null) {
                     unknownAttributes = new ArrayList<String>();
                 }

core-api/src/main/java/com/optimizely/ab/bucketing/Bucketer.java

@@ -76,87 +76,90 @@ private String bucketToEntity(int bucketValue, List<TrafficAllocation> trafficAl
     }
 
     private Experiment bucketToExperiment(@Nonnull Group group,
-                                          @Nonnull String userId) {
+                                          @Nonnull String bucketingId) {
         // "salt" the bucket id using the group id
-        String bucketId = userId + group.getId();
+        String bucketKey = bucketingId + group.getId();
 
         List<TrafficAllocation> trafficAllocations = group.getTrafficAllocation();
 
-        int hashCode = MurmurHash3.murmurhash3_x86_32(bucketId, 0, bucketId.length(), MURMUR_HASH_SEED);
+        int hashCode = MurmurHash3.murmurhash3_x86_32(bucketKey, 0, bucketKey.length(), MURMUR_HASH_SEED);
         int bucketValue = generateBucketValue(hashCode);
-        logger.debug("Assigned bucket {} to user \"{}\" during experiment bucketing.", bucketValue, userId);
+        logger.debug("Assigned bucket {} to user with bucketingId \"{}\" during experiment bucketing.", bucketValue, bucketingId);
 
         String bucketedExperimentId = bucketToEntity(bucketValue, trafficAllocations);
         if (bucketedExperimentId != null) {
             return projectConfig.getExperimentIdMapping().get(bucketedExperimentId);
         }
 
         // user was not bucketed to an experiment in the group
-        logger.info("User \"{}\" is not in any experiment of group {}.", userId, group.getId());
         return null;
     }
 
     private Variation bucketToVariation(@Nonnull Experiment experiment,
-                                        @Nonnull String userId) {
+                                        @Nonnull String bucketingId) {
         // "salt" the bucket id using the experiment id
         String experimentId = experiment.getId();
         String experimentKey = experiment.getKey();
-        String combinedBucketId = userId + experimentId;
+        String combinedBucketId = bucketingId + experimentId;
 
         List<TrafficAllocation> trafficAllocations = experiment.getTrafficAllocation();
 
         int hashCode = MurmurHash3.murmurhash3_x86_32(combinedBucketId, 0, combinedBucketId.length(), MURMUR_HASH_SEED);
         int bucketValue = generateBucketValue(hashCode);
-        logger.debug("Assigned bucket {} to user \"{}\" during variation bucketing.", bucketValue, userId);
+        logger.debug("Assigned bucket {} to user with bucketingId \"{}\" when bucketing to a variation.", bucketValue, bucketingId);
 
         String bucketedVariationId = bucketToEntity(bucketValue, trafficAllocations);
         if (bucketedVariationId != null) {
             Variation bucketedVariation = experiment.getVariationIdToVariationMap().get(bucketedVariationId);
             String variationKey = bucketedVariation.getKey();
-            logger.info("User \"{}\" is in variation \"{}\" of experiment \"{}\".", userId, variationKey,
-                        experimentKey);
+            logger.info("User with bucketingId \"{}\" is in variation \"{}\" of experiment \"{}\".", bucketingId, variationKey,
+                    experimentKey);
 
             return bucketedVariation;
         }
 
         // user was not bucketed to a variation
-        logger.info("User \"{}\" is not in any variation of experiment \"{}\".", userId, experimentKey);
+        logger.info("User with bucketingId \"{}\" is not in any variation of experiment \"{}\".", bucketingId, experimentKey);
         return null;
     }
 
     /**
      * Assign a {@link Variation} of an {@link Experiment} to a user based on hashed value from murmurhash3.
      * @param experiment The Experiment in which the user is to be bucketed.
-     * @param userId User Identifier
+     * @param bucketingId string A customer-assigned value used to create the key for the murmur hash.
      * @return Variation the user is bucketed into or null.
      */
     public @Nullable Variation bucket(@Nonnull Experiment experiment,
-                                      @Nonnull String userId) {
+                                      @Nonnull String bucketingId) {
         // ---------- Bucket User ----------
         String groupId = experiment.getGroupId();
         // check whether the experiment belongs to a group
         if (!groupId.isEmpty()) {
             Group experimentGroup = projectConfig.getGroupIdMapping().get(groupId);
             // bucket to an experiment only if group entities are to be mutually exclusive
             if (experimentGroup.getPolicy().equals(Group.RANDOM_POLICY)) {
-                Experiment bucketedExperiment = bucketToExperiment(experimentGroup, userId);
+                Experiment bucketedExperiment = bucketToExperiment(experimentGroup, bucketingId);
                 if (bucketedExperiment == null) {
+                    logger.info("User with bucketingId \"{}\" is not in any experiment of group {}.", bucketingId, experimentGroup.getId());
                     return null;
+                }
+                else {
+
                 }
                 // if the experiment a user is bucketed in within a group isn't the same as the experiment provided,
                 // don't perform further bucketing within the experiment
                 if (!bucketedExperiment.getId().equals(experiment.getId())) {
-                    logger.info("User \"{}\" is not in experiment \"{}\" of group {}.", userId, experiment.getKey(),
+                    logger.info("User with bucketingId \"{}\" is not in experiment \"{}\" of group {}.", bucketingId, experiment.getKey(),
                             experimentGroup.getId());
                     return null;
                 }
 
-                logger.info("User \"{}\" is in experiment \"{}\" of group {}.", userId, experiment.getKey(),
+                logger.info("User with bucketingId \"{}\" is in experiment \"{}\" of group {}.", bucketingId, experiment.getKey(),
                         experimentGroup.getId());
             }
         }
 
-        return bucketToVariation(experiment, userId);
+        return bucketToVariation(experiment, bucketingId);
     }
 
 

core-api/src/main/java/com/optimizely/ab/bucketing/DecisionService.java

@@ -42,6 +42,7 @@
  */
 public class DecisionService {
 
+    public static final String BUCKETING_ATTRIBUTE = "$opt_bucketing_id";
     private final Bucketer bucketer;
     private final ErrorHandler errorHandler;
     private final ProjectConfig projectConfig;
@@ -95,6 +96,7 @@ public DecisionService(@Nonnull Bucketer bucketer,
 
         // fetch the user profile map from the user profile service
         UserProfile userProfile = null;
+        
         if (userProfileService != null) {
             try {
                 Map<String, Object> userProfileMap = userProfileService.lookup(userId);
@@ -123,7 +125,11 @@ public DecisionService(@Nonnull Bucketer bucketer,
         }
 
         if (ExperimentUtils.isUserInExperiment(projectConfig, experiment, filteredAttributes)) {
-            variation = bucketer.bucket(experiment, userId);
+            String bucketingId = userId;
+            if (filteredAttributes.containsKey(BUCKETING_ATTRIBUTE)) {
+                bucketingId = filteredAttributes.get(BUCKETING_ATTRIBUTE);
+            }
+            variation = bucketer.bucket(experiment, bucketingId);
 
             if (variation != null) {
                 if (userProfileService != null) {

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

@@ -17,6 +17,7 @@
 package com.optimizely.ab.event.internal;
 
 import com.optimizely.ab.annotations.VisibleForTesting;
+import com.optimizely.ab.bucketing.DecisionService;
 import com.optimizely.ab.config.Attribute;
 import com.optimizely.ab.config.Experiment;
 import com.optimizely.ab.config.ProjectConfig;
@@ -49,6 +50,7 @@ public class EventBuilderV2 extends EventBuilder {
 
     static final String IMPRESSION_ENDPOINT = "https://logx.optimizely.com/log/decision";
     static final String CONVERSION_ENDPOINT = "https://logx.optimizely.com/log/event";
+    static final String ATTRIBUTE_KEY_FOR_BUCKETING_ATTRIBUTE = "optimizely_bucketing_id";
 
     @VisibleForTesting
     public final ClientEngine clientEngine;
@@ -159,13 +161,22 @@ private List<Feature> createUserFeatures(Map<String, String> attributes, Project
             String attributeKey = attributeEntry.getKey();
             Attribute attribute = attributeKeyMapping.get(attributeKey);
 
+            if (attributeEntry.getKey() == DecisionService.BUCKETING_ATTRIBUTE) {
+                features.add(new Feature(com.optimizely.ab.bucketing.DecisionService.BUCKETING_ATTRIBUTE,
+                        ATTRIBUTE_KEY_FOR_BUCKETING_ATTRIBUTE,
+                        Feature.CUSTOM_ATTRIBUTE_FEATURE_TYPE,
+                        attributeEntry.getValue(), true));
+                continue;
+            }
+
             if (attribute == null) {
                 logger.warn("Attempting to use unknown attribute key: {}. Attribute will be ignored", attributeKey);
                 continue;
             }
 
             features.add(new Feature(attribute.getId(), attributeKey, Feature.CUSTOM_ATTRIBUTE_FEATURE_TYPE,
-                                     attributeEntry.getValue(), true));
+                        attributeEntry.getValue(), true));
+
         }
 
         return features;