Sharing - added javadocs; changed some public methods to package-private (#18)

Author: jon8787

src/main/java/com/uid2/client/DecryptionResponse.java

@@ -9,22 +9,31 @@ public class DecryptionResponse {
     private final Integer siteId;
     private final Integer siteKeySiteId;
 
-    public DecryptionResponse(DecryptionStatus status, String uid, Instant established, Integer siteId, Integer siteKeySiteId) {
+    DecryptionResponse(DecryptionStatus status, String uid, Instant established, Integer siteId, Integer siteKeySiteId) {
         this.status = status;
         this.uid = uid;
         this.established = established;
         this.siteId = siteId;
         this.siteKeySiteId = siteKeySiteId;
     }
 
+    /**
+     * @return whether the decryption was successful.
+     */
     public boolean isSuccess() {
         return status == DecryptionStatus.SUCCESS;
     }
 
+    /**
+     * @return the decryption result status. See {@link DecryptionStatus}.
+     */
     public DecryptionStatus getStatus() {
         return status;
     }
 
+    /**
+     * @return the raw UID.
+     */
     public String getUid() {
         return uid;
     }
@@ -37,11 +46,11 @@ public Instant getEstablished() {
 
     public Integer getSiteKeySiteId() { return siteKeySiteId; }
 
-    public static DecryptionResponse makeError(DecryptionStatus status) {
+    static DecryptionResponse makeError(DecryptionStatus status) {
         return new DecryptionResponse(status, null, Instant.MIN, null, null);
     }
 
-    public static DecryptionResponse makeError(DecryptionStatus status, Instant established, Integer siteId, Integer siteKeySiteId) {
+    static DecryptionResponse makeError(DecryptionStatus status, Instant established, Integer siteId, Integer siteKeySiteId) {
         return new DecryptionResponse(status, null, established, siteId, siteKeySiteId);
     }
 }

src/main/java/com/uid2/client/DecryptionStatus.java

@@ -1,14 +1,47 @@
  package com.uid2.client;
 
+ /**
+  * DecryptionStatus: Indicates the result of a decrypt() call.
+  */
 public enum DecryptionStatus {
+
     SUCCESS,
-    NOT_AUTHORIZED_FOR_MASTER_KEY, //note this error can occur for old tokens also, since old encryption keys are regularly deleted
+     /**
+      * NOT_AUTHORIZED_FOR_MASTER_KEY can occur for old tokens, when the master key used to encrypt it has been deleted (eg after 30 days).
+      * It can also occur for participants that have been removed from the UID platform, and therefore no longer have access to master keys.
+      */
+    NOT_AUTHORIZED_FOR_MASTER_KEY,
+     /**
+      * NOT_AUTHORIZED_FOR_KEY can occur when decrypting a token from a participant that has not granted sharing access to the receiver.
+      */
     NOT_AUTHORIZED_FOR_KEY,
+     /**
+      * NOT_INITIALIZED: IUID2Client.refresh() has not been called or did not succeed.
+      */
     NOT_INITIALIZED,
+     /**
+      * INVALID_PAYLOAD: The UID token passed to decrypt() was invalid.
+      */
     INVALID_PAYLOAD,
+     /**
+      * EXPIRED_TOKEN: The token has expired and so must not be used. See also NOT_AUTHORIZED_FOR_MASTER_KEY.
+      */
     EXPIRED_TOKEN,
+     /**
+      * KEYS_NOT_SYNCED: The encryption keys have expired. This can happen if IUID2Client.refresh() has not been called for a long time.
+      */
     KEYS_NOT_SYNCED,
-    VERSION_NOT_SUPPORTED,
+     /**
+      * VERSION_NOT_SUPPORTED: The token version being decrypted is too new for this SDK. Ensure you have the latest version of the SDK.
+      */
+     VERSION_NOT_SUPPORTED,
+     /**
+      * INVALID_PAYLOAD_TYPE: This is a value returned by the legacy decryptData() method. Use decrypt() instead.
+      */
     INVALID_PAYLOAD_TYPE,
+     /**
+      * INVALID_IDENTITY_SCOPE: Either UID2ClientFactory.create() was used to decrypt an EUID token, or EUIDClientFactory.create() was used
+      * to decrypt a UID2 token. Ensure the factory class matches the token type you are decrypting.
+      */
     INVALID_IDENTITY_SCOPE,
 }

src/main/java/com/uid2/client/EncryptionDataResponse.java

@@ -4,18 +4,29 @@ public class EncryptionDataResponse {
     private final EncryptionStatus status;
     private final String encryptedData;
 
-    public EncryptionDataResponse(EncryptionStatus status, String encryptedData) {
+    EncryptionDataResponse(EncryptionStatus status, String encryptedData) {
         this.status = status;
         this.encryptedData = encryptedData;
     }
 
+    /**
+     * @return whether the encryption was successful.
+     */
     public boolean isSuccess() {
         return status == EncryptionStatus.SUCCESS;
     }
+
+    /**
+     * @return the encryption result status. See {@link EncryptionStatus}
+     */
     public EncryptionStatus getStatus() { return status; }
+
+    /**
+     * @return the UID token
+     */
     public String getEncryptedData() { return encryptedData; }
 
-    public static EncryptionDataResponse makeError(EncryptionStatus status) {
+    static EncryptionDataResponse makeError(EncryptionStatus status) {
         return new EncryptionDataResponse(status, null);
     }
 }

src/main/java/com/uid2/client/EncryptionStatus.java

@@ -2,11 +2,32 @@
 
 public enum EncryptionStatus {
     SUCCESS,
+    /**
+     * NOT_AUTHORIZED_FOR_MASTER_KEY: Indicates that the participant has been removed from the UID platform.
+     */
     NOT_AUTHORIZED_FOR_MASTER_KEY,
+    /**
+     * NOT_AUTHORIZED_FOR_KEY: The participant has not been enabled for encryption.
+     */
     NOT_AUTHORIZED_FOR_KEY,
+    /**
+     * NOT_INITIALIZED: IUID2Client.refresh() has not been called or did not succeed.
+     */
     NOT_INITIALIZED,
+    /**
+     * KEYS_NOT_SYNCED: The encryption keys have expired. This can happen if IUID2Client.refresh() has not been called for a long time.
+     */
     KEYS_NOT_SYNCED,
+    /**
+     * TOKEN_DECRYPT_FAILURE: This is a value returned by the legacy encryptData() method. Use encrypt() instead.
+     */
     TOKEN_DECRYPT_FAILURE,
+    /**
+     * KEY_INACTIVE: This is a value returned by the legacy encryptData() method. Use encrypt() instead.
+     */
     KEY_INACTIVE,
+    /**
+     * ENCRYPTION_FAILURE: An exception was thrown during encryption.
+     */
     ENCRYPTION_FAILURE,
 }

src/main/java/com/uid2/client/IUID2Client.java

@@ -4,10 +4,17 @@
 
 public interface IUID2Client {
 
+    /**
+     * Refreshes encryption keys. Call this regularly (eg every hour) to ensure keys are up to date.
+     */
     void refresh() throws UID2ClientException;
 
     DecryptionResponse decrypt(String token, Instant now) throws UID2ClientException;
 
+    /**
+     * @param token The UID token to be decrypted into a raw UID
+     * @return See {@link DecryptionResponse}
+     */
     default DecryptionResponse decrypt(String token) throws UID2ClientException
     {
         return decrypt(token, Instant.now());
@@ -20,6 +27,10 @@ default DecryptionResponse decrypt(String token) throws UID2ClientException
     @Deprecated
     EncryptionDataResponse encryptData(EncryptionDataRequest request) throws UID2ClientException;
 
+    /**
+     * @param rawUid The raw UID to be encrypted into a UID token
+     * @return An EncryptionDataResponse, containing success status and the UID token
+     */
     EncryptionDataResponse encrypt(String rawUid) throws UID2ClientException;
 
     /**