Merge pull request #15 from zfi/master

Merging branch 1.2 to master for release

.gitignore

@@ -11,4 +11,6 @@ nbactions.xml
 ## IntelliJ
 #################
 
-.idea
+.idea
+Cloud-Session-java-client.iml
+

pom.xml

@@ -7,8 +7,8 @@
     <packaging>jar</packaging>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <maven.compiler.source>1.7</maven.compiler.source>
-        <maven.compiler.target>1.7</maven.compiler.target>
+        <maven.compiler.source>1.8</maven.compiler.source>
+        <maven.compiler.target>1.8</maven.compiler.target>
     </properties>
 
     <dependencies>

src/main/java/com/parallax/client/cloudsession/CloudSessionAuthenticateService.java

@@ -23,48 +23,124 @@
 import org.slf4j.LoggerFactory;
 
 /**
- *
+ * Authenticate user login
+ * <p>
+ * Provides an interface to the Could-Session server for user authentication
+ * services. The methods in this class use custom exceptions to indicate 
+ * a situation where a program fault has been detected.
+ * 
  * @author Michel
+ * 
  */
 public class CloudSessionAuthenticateService {
 
+    /**
+     * Handle for any logging activity
+     */
     private final Logger LOG = LoggerFactory.getLogger(CloudSessionAuthenticateService.class);
+
+    /**
+     * Base URL use to obtain authentication service.
+     */
     private final String BASE_URL;
+
+    /**
+     * Host name
+     */
     private final String SERVER;
 
+    /**
+     * Class constructor
+     * 
+     * @param server The cloud session host name
+     * @param baseUrl The cloud session URL as defined in the 
+     * blocklyprop.properties file
+     */
     public CloudSessionAuthenticateService(String server, String baseUrl) {
         this.SERVER = server;
         this.BASE_URL = baseUrl;
 
     }
 
-    public User authenticateLocalUser(String login, String password) throws UnknownUserException, UserBlockedException, EmailNotConfirmedException, InsufficientBucketTokensException, WrongAuthenticationSourceException, ServerException {
+    /**
+     * Authenticate user from local authentication database
+     * 
+     * @param login
+     * @param password
+     * @return
+     * @throws UnknownUserException
+     * @throws UserBlockedException
+     * @throws EmailNotConfirmedException
+     * @throws InsufficientBucketTokensException
+     * @throws WrongAuthenticationSourceException
+     * @throws ServerException
+     */
+    public User authenticateLocalUser(String login, String password) 
+            throws
+                UnknownUserException, 
+                UserBlockedException, 
+                EmailNotConfirmedException, 
+                InsufficientBucketTokensException, 
+                WrongAuthenticationSourceException, 
+                ServerException {
+
+        LOG.debug("Attempting to authenticate user: {}", login);
+
         try {
             Map<String, String> data = new HashMap<>();
             data.put("email", login);
             data.put("password", password);
-            HttpRequest httpRequest = HttpRequest.post(getUrl("/authenticate/local")).header("server", SERVER).form(data);
-            String response = httpRequest.body();
 
+            // Issue POST request to attempt login
+            HttpRequest httpRequest = HttpRequest
+                    .post(getUrl("/authenticate/local"))
+                    .header("server", SERVER)
+                    .form(data);
+
+            // Convert response from login attempt
+            String response = httpRequest.body();
+
+            LOG.debug("Received a response: {}", response);
+
             JsonElement jelement = new JsonParser().parse(response);
             JsonObject responseObject = jelement.getAsJsonObject();
+
             if (responseObject.get("success").getAsBoolean()) {
+                // Create and return a user object
                 JsonObject userJson = responseObject.get("user").getAsJsonObject();
                 User user = new User();
+
                 user.setId(userJson.get("id").getAsLong());
                 user.setEmail(userJson.get("email").getAsString());
                 user.setLocale(userJson.get("locale").getAsString());
                 user.setScreenname(userJson.get("screenname").getAsString());
+                user.setAuthenticationSource(userJson.get("authentication-source").getAsString());
+
+                // These dates might be zero for grandfathered accounts
+                user.setBirthMonth(userJson.get("bdmonth").getAsInt());
+                user.setBirthYear(userJson.get("bdyear").getAsInt());
+
+                // This gets stored as a Null if the sponsor address is not supplied
+                if (userJson.get("parent-email").isJsonNull()) {
+                    user.setCoachEmail("");
+                }
+                else {
+                    user.setCoachEmail(userJson.get("parent-email").getAsString());
+                }
+                user.setCoachEmailSource(userJson.get("parent-email-source").getAsInt());
+
                 return user;
             } else {
+                // Authentication failed. Obtain result code
                 String message = responseObject.get("message").getAsString();
                 switch (responseObject.get("code").getAsInt()) {
                     case 400:
                         throw new UnknownUserException(login, message);
                     case 410:
-                        // Wrong password
+                        // Wrong password, but we should report it as an
+                        // unknow username OR password to increase ambiguity
                         LOG.info("Wrong password");
-                        return null;
+                        throw new UnknownUserException(login, message);
                     case 420:
                         throw new UserBlockedException(message);
                     case 430:
@@ -82,13 +158,18 @@ public User authenticateLocalUser(String login, String password) throws UnknownU
             LOG.error("Inter service error", hre);
             throw new ServerException(hre);
         } catch (JsonSyntaxException jse) {
-            LOG.error("Json syntace service error", jse);
+            LOG.error("Json syntax error", jse);
             throw new ServerException(jse);
         }
     }
 
+    /**
+     * Prepend the base url to the action url
+     * 
+     * @param actionUrl
+     * @return 
+     */
     private String getUrl(String actionUrl) {
         return BASE_URL + actionUrl;
     }
-
 }

src/main/java/com/parallax/client/cloudsession/CloudSessionAuthenticationTokenService.java

@@ -32,6 +32,11 @@ public class CloudSessionAuthenticationTokenService {
     private final String BASE_URL;
     private final String SERVER;
 
+    /**
+     *
+     * @param server
+     * @param baseUrl
+     */
     public CloudSessionAuthenticationTokenService(String server, String baseUrl) {
         this.SERVER = server;
         this.BASE_URL = baseUrl;
@@ -41,6 +46,17 @@ private String getUrl(String actionUrl) {
         return BASE_URL + actionUrl;
     }
 
+    /**
+     *
+     * @param idUser
+     * @param browser
+     * @param ipAddress
+     * @return
+     * @throws UnknownUserIdException
+     * @throws UserBlockedException
+     * @throws EmailNotConfirmedException
+     * @throws ServerException
+     */
     public String request(Long idUser, String browser, String ipAddress) throws UnknownUserIdException, UserBlockedException, EmailNotConfirmedException, ServerException {
         try {
             Map<String, String> data = new HashMap<>();
@@ -76,6 +92,15 @@ public String request(Long idUser, String browser, String ipAddress) throws Unkn
         }
     }
 
+    /**
+     *
+     * @param token
+     * @param idUser
+     * @param browser
+     * @param ipAddress
+     * @return
+     * @throws ServerException
+     */
     public boolean doConfirm(String token, Long idUser, String browser, String ipAddress) throws ServerException {
         try {
             Map<String, String> data = new HashMap<>();
@@ -104,6 +129,14 @@ public boolean doConfirm(String token, Long idUser, String browser, String ipAdd
         }
     }
 
+    /**
+     *
+     * @param idUser
+     * @param browser
+     * @param ipAddress
+     * @return
+     * @throws ServerException
+     */
     public List<String> getTokens(Long idUser, String browser, String ipAddress) throws ServerException {
         try {
             Map<String, String> data = new HashMap<>();

src/main/java/com/parallax/client/cloudsession/CloudSessionBucketService.java

@@ -28,16 +28,67 @@ public class CloudSessionBucketService {
     private final Logger LOG = LoggerFactory.getLogger(CloudSessionBucketService.class);
     private final String BASE_URL;
 
+    /**
+     *
+     * @param baseUrl
+     */
     public CloudSessionBucketService(String baseUrl) {
         this.BASE_URL = baseUrl;
     }
 
-    public boolean consumeOne(String type, Long id) throws UnknownUserIdException, UnknownBucketTypeException, InsufficientBucketTokensException, EmailNotConfirmedException, UserBlockedException, ServerException {
+    /**
+     *  Inform the Cloud Session service to decrement the token count for
+     *  the specified 'type' of token
+     * 
+     * @param type token type
+     * @param id user ID
+     * 
+     * @return  true if successful or raise an exception if unsuccessful
+     * 
+     * @throws UnknownUserIdException
+     * @throws UnknownBucketTypeException
+     * @throws InsufficientBucketTokensException
+     * @throws EmailNotConfirmedException
+     * @throws UserBlockedException
+     * @throws ServerException
+     */
+    public boolean consumeOne(String type, Long id) throws 
+            UnknownUserIdException, 
+            UnknownBucketTypeException, 
+            InsufficientBucketTokensException, 
+            EmailNotConfirmedException, 
+            UserBlockedException, 
+            ServerException {
+
         HttpRequest request = HttpRequest.get(getUrl("/bucket/consume/" + type + "/" + id));
         return handleResponse(type, id, request);
     }
 
-    public boolean consume(String type, Long id, int count) throws UnknownUserIdException, UnknownBucketTypeException, InsufficientBucketTokensException, EmailNotConfirmedException, UserBlockedException, ServerException {
+    /**
+     *  Inform the Cloud Session service to decrement the token count by
+     * 'count' tokens for the specified 'type' of token 
+     *
+     * @param type token type
+     * @param id user ID
+     * @param count number of tokens to remove from the queue
+     * 
+     * @return true if successful or raise an exception if unsuccessful
+     * 
+     * @throws UnknownUserIdException
+     * @throws UnknownBucketTypeException
+     * @throws InsufficientBucketTokensException
+     * @throws EmailNotConfirmedException
+     * @throws UserBlockedException
+     * @throws ServerException
+     */
+    public boolean consume(String type, Long id, int count) throws
+            UnknownUserIdException, 
+            UnknownBucketTypeException, 
+            InsufficientBucketTokensException, 
+            EmailNotConfirmedException, 
+            UserBlockedException, 
+            ServerException {
+
         HttpRequest request = HttpRequest.get(getUrl("/bucket/consume/" + type + "/" + id + "/" + count));
         return handleResponse(type, id, request);
     }
@@ -46,14 +97,33 @@ private String getUrl(String actionUrl) {
         return BASE_URL + actionUrl;
     }
 
-    protected boolean handleResponse(String type, Long id, HttpRequest request) throws UnknownUserIdException, UnknownBucketTypeException, InsufficientBucketTokensException, EmailNotConfirmedException, UserBlockedException, ServerException {
+    /**
+     *
+     * @param type
+     * @param id
+     * @param request
+     * @return
+     * @throws UnknownUserIdException
+     * @throws UnknownBucketTypeException
+     * @throws InsufficientBucketTokensException
+     * @throws EmailNotConfirmedException
+     * @throws UserBlockedException
+     * @throws ServerException
+     */
+    protected boolean handleResponse(String type, Long id, HttpRequest request) throws
+            UnknownUserIdException, 
+            UnknownBucketTypeException, 
+            InsufficientBucketTokensException, 
+            EmailNotConfirmedException, 
+            UserBlockedException, 
+            ServerException {
+
         try {
-            //        int responseCode = request.code();
-//        System.out.println("Response code: " + responseCode);
             String response = request.body();
-//        System.out.println(response);
+
             JsonElement jelement = new JsonParser().parse(response);
             JsonObject responseObject = jelement.getAsJsonObject();
+
             if (responseObject.get("success").getAsBoolean()) {
                 return true;
             } else {
@@ -66,7 +136,10 @@ protected boolean handleResponse(String type, Long id, HttpRequest request) thro
                     case 430:
                         throw new EmailNotConfirmedException(message);
                     case 470:
+                        // Rate exceeded - no tokens are left in the bucket
                         String nextTime = responseObject.get("data").getAsString();
+                        LOG.info("Compile bucket empty. Time to next token is:", nextTime);
+
                         throw new InsufficientBucketTokensException(message, nextTime);
                     case 480:
                         throw new UnknownBucketTypeException(type, message);