user profile service map structure (#96)

* Create UserProfileService keys
* create user profile class of the interface

Author: wangjoshuah

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

@@ -16,6 +16,7 @@
  */
 package com.optimizely.ab.bucketing;
 
+import java.util.HashMap;
 import java.util.Map;
 
 /**
@@ -25,12 +26,65 @@
  */
 public interface UserProfileService {
 
+    /**
+     * A class representing a user's profile.
+     */
+    class UserProfile {
+
+        /** A user's ID. */
+        public final String userId;
+        /** The bucketing decisions of the user. */
+        public final Map<String, String> decisions;
+
+        /**
+         * Construct a User Profile instance from explicit components.
+         * @param userId The ID of the user.
+         * @param decisions The bucketing decisions of the user.
+         */
+        public UserProfile(String userId, Map<String, String> decisions) {
+            this.userId = userId;
+            this.decisions = decisions;
+        }
+
+        /**
+         * Construct a User Profile instance from a Map.
+         * @param userProfileMap A {@code Map<String, Object>} containing the properties of the user profile.
+         */
+        @SuppressWarnings("unchecked")
+        public UserProfile(Map<String, Object> userProfileMap) {
+            this((String) userProfileMap.get(userIdKey), (Map<String, String>) userProfileMap.get(decisionsKey));
+        }
+
+        /**
+         * Convert a User Profile instance to a Map.
+         * @return A map representation of the user profile instance.
+         */
+        Map<String, Object> toMap() {
+            Map<String, Object> userProfileMap = new HashMap<String, Object>(2);
+            userProfileMap.put(userIdKey, userId);
+            userProfileMap.put(decisionsKey, decisions);
+            return userProfileMap;
+        }
+    }
+
+    /** The key for the user ID. Returns a String.*/
+    String userIdKey = "user_id";
+    /** The key for the decisions Map. Returns a {@code Map<String, String>}.*/
+    String decisionsKey = "decisions";
+
     /**
      * Fetch the user profile map for the user ID.
      *
      * @param userId The ID of the user whose profile will be retrieved.
      * @return a Map representing the user's profile.
-     * @throws Exception 
+     * The returned {@code Map<String, Object>} of the user profile will have the following structure.
+     * {
+     *     userIdKey : String userId,
+     *     decisionsKey : {@code Map<String, String>} decisions {
+     *          String experimentId : String variationId
+     *     }
+     * }
+     * @throws Exception Passes on whatever exceptions the implementation may throw.
      */
     Map<String, Object> lookup(String userId) throws Exception;