Update JavaDoc

Author: sgonzalezMSFT

src/main/java/com/microsoft/aad/msal4j/Account.java

@@ -28,6 +28,10 @@
 import lombok.Setter;
 import lombok.experimental.Accessors;
 
+/**
+ * Representation of a single user account. If modifying this object, ensure it is compliant with
+ * cache persistent model
+ */
 @Accessors(fluent = true)
 @Getter
 @Setter

src/main/java/com/microsoft/aad/msal4j/AppMetadataCacheEntity.java

@@ -31,10 +31,13 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Representation of application metadata.
+ */
 @Accessors(fluent = true)
 @Getter
 @Setter
-public class AppMetadataCacheEntity {
+class AppMetadataCacheEntity {
 
     public static final String APP_METADATA_CACHE_ENTITY_ID = "appmetadata";
 

src/main/java/com/microsoft/aad/msal4j/AuthorizationCodeParameters.java

@@ -31,6 +31,11 @@
 
 import static com.microsoft.aad.msal4j.ParameterValidationUtils.validateNotBlank;
 
+/**
+ * Object containing parameters for authorization code flow. Can be used as parameter to
+ * {@link PublicClientApplication#acquireToken(AuthorizationCodeParameters)} or to
+ * {@link ConfidentialClientApplication#acquireToken(AuthorizationCodeParameters)}
+ */
 @Builder
 @Accessors(fluent = true)
 @Getter
@@ -50,6 +55,12 @@ private static AuthorizationCodeParametersBuilder builder() {
         return new AuthorizationCodeParametersBuilder();
     }
 
+    /**
+     * Builder for {@link AuthorizationCodeParameters}
+     * @param authorizationCode code received from the service authorization endpoint
+     * @param redirectUri URI where authorization code was received
+     * @return builder object that can be used to construct {@link AuthorizationCodeParameters}
+     */
     public static AuthorizationCodeParametersBuilder builder(String authorizationCode, URI redirectUri) {
 
         validateNotBlank("authorizationCode", authorizationCode);

src/main/java/com/microsoft/aad/msal4j/ClientApplicationBase.java

@@ -129,6 +129,44 @@ CompletableFuture<IAuthenticationResult> executeRequest(
         return future;
     }
 
+    @Override
+    public CompletableFuture<IAuthenticationResult> acquireTokenSilently(SilentParameters parameters)
+            throws MalformedURLException {
+
+        validateNotNull("parameters", parameters);
+
+        SilentRequest silentRequest = new SilentRequest(
+                parameters,
+                this,
+                createRequestContext(PublicApi.ACQUIRE_TOKEN_SILENTLY));
+
+        return executeRequest(silentRequest);
+    }
+
+    @Override
+    public CompletableFuture<Set<IAccount>> getAccounts() {
+        MsalRequest msalRequest =
+                new MsalRequest(this, null,
+                        createRequestContext(PublicApi.GET_ACCOUNTS)){};
+
+        AccountsSupplier supplier = new AccountsSupplier(this, msalRequest);
+
+        CompletableFuture<Set<IAccount>> future =
+                serviceBundle.getExecutorService() != null ? CompletableFuture.supplyAsync(supplier, serviceBundle.getExecutorService())
+                        : CompletableFuture.supplyAsync(supplier);
+        return future;
+    }
+
+    @Override
+    public CompletableFuture removeAccount(IAccount account) {
+        RemoveAccountRunnable runnable = new RemoveAccountRunnable(this, account);
+
+        CompletableFuture<Void> future =
+                serviceBundle.getExecutorService() != null ? CompletableFuture.runAsync(runnable, serviceBundle.getExecutorService())
+                        : CompletableFuture.runAsync(runnable);
+        return future;
+    }
+
     AuthenticationResult acquireTokenCommon(MsalRequest msalRequest, Authority requestAuthority)
             throws Exception {
 
@@ -186,44 +224,6 @@ ServiceBundle getServiceBundle() {
         return serviceBundle;
     }
 
-    @Override
-    public CompletableFuture<IAuthenticationResult> acquireTokenSilently(SilentParameters parameters)
-            throws MalformedURLException {
-
-        validateNotNull("parameters", parameters);
-
-        SilentRequest silentRequest = new SilentRequest(
-                parameters,
-                this,
-                createRequestContext(PublicApi.ACQUIRE_TOKEN_SILENTLY));
-
-        return executeRequest(silentRequest);
-    }
-
-    @Override
-    public CompletableFuture<Set<IAccount>> getAccounts() {
-        MsalRequest msalRequest =
-                new MsalRequest(this, null,
-                        createRequestContext(PublicApi.GET_ACCOUNTS)){};
-
-        AccountsSupplier supplier = new AccountsSupplier(this, msalRequest);
-
-        CompletableFuture<Set<IAccount>> future =
-                serviceBundle.getExecutorService() != null ? CompletableFuture.supplyAsync(supplier, serviceBundle.getExecutorService())
-                        : CompletableFuture.supplyAsync(supplier);
-        return future;
-    }
-
-    @Override
-    public CompletableFuture removeAccount(IAccount account) {
-        RemoveAccountRunnable runnable = new RemoveAccountRunnable(this, account);
-
-        CompletableFuture<Void> future =
-                serviceBundle.getExecutorService() != null ? CompletableFuture.runAsync(runnable, serviceBundle.getExecutorService())
-                        : CompletableFuture.runAsync(runnable);
-        return future;
-    }
-
     protected static String canonicalizeUrl(String authority) {
         authority = authority.toLowerCase();
 
@@ -272,7 +272,6 @@ public Builder(String clientId) {
          * @return instance of the Builder on which method was called
          * @throws MalformedURLException if val is malformed URL
          */
-
         public T authority(String val) throws MalformedURLException {
             authority = canonicalizeUrl(val);
 

src/main/java/com/microsoft/aad/msal4j/ClientAssertion.java

@@ -28,7 +28,7 @@
 import lombok.Getter;
 import lombok.experimental.Accessors;
 
-/***
+/**
  * Credential type containing an assertion of type
  * "urn:ietf:params:oauth:token-type:jwt".
  */
@@ -44,8 +44,7 @@ public final class ClientAssertion {
      * Constructor to create credential with a jwt token encoded as a base64 url
      * encoded string.
      *
-     * @param assertion
-     *            The jwt used as credential.
+     * @param assertion The jwt used as credential.
      */
     public ClientAssertion(final String assertion) {
         if (StringHelper.isBlank(assertion)) {

src/main/java/com/microsoft/aad/msal4j/ClientCredentialFactory.java

@@ -29,22 +29,47 @@
 import java.security.cert.CertificateException;
 import java.security.cert.X509Certificate;
 
+/**
+ * Factory for creating client credentials used in confidential client flows
+ */
 public class ClientCredentialFactory {
 
+    /**
+     *
+     * @param secret secret of application requesting a token
+     * @return {@link ClientSecret}
+     */
     public static IClientCredential create(String secret){
         return new ClientSecret(secret);
     }
 
+    /**
+     *
+     * @param pkcs12Certificate InputStream containing PCKS12 formatted certificate
+     * @param password certificate password
+     * @return {@link IClientCredential}
+     * @throws CertificateException
+     * @throws UnrecoverableKeyException
+     * @throws NoSuchAlgorithmException
+     * @throws KeyStoreException
+     * @throws NoSuchProviderException
+     * @throws IOException
+     */
     public static IClientCredential create
             (final InputStream pkcs12Certificate, final String password)
             throws CertificateException, UnrecoverableKeyException, NoSuchAlgorithmException,
             KeyStoreException, NoSuchProviderException, IOException {
         return AsymmetricKeyCredential.create(pkcs12Certificate, password);
     }
 
+    /**
+     *
+     * @param key  RSA private key to sign the assertion.
+     * @param publicCertificate x509 public certificate used for thumbprint
+     * @return {@link IClientCredential}
+     */
     public static IClientCredential create
-            (final PrivateKey key, final X509Certificate publicCertificate)
-    {
+            (final PrivateKey key, final X509Certificate publicCertificate) {
         return AsymmetricKeyCredential.create(key, publicCertificate);
     }
 }

src/main/java/com/microsoft/aad/msal4j/ClientCredentialParameters.java

@@ -30,6 +30,10 @@
 
 import static com.microsoft.aad.msal4j.ParameterValidationUtils.validateNotEmpty;
 
+/**
+ * Object containing parameters for client credential flow. Can be used as parameter to
+ * {@link ConfidentialClientApplication#acquireToken(ClientCredentialParameters)}
+ */
 @Builder
 @Accessors(fluent = true)
 @Getter
@@ -44,6 +48,11 @@ private static ClientCredentialParametersBuilder builder() {
         return new ClientCredentialParametersBuilder();
     }
 
+    /**
+     * Builder for {@link ClientCredentialParameters}
+     * @param scopes scopes application is requesting access to
+     * @return builder that can be used to construct ClientCredentialParameters
+     */
     public static ClientCredentialParametersBuilder builder(Set<String> scopes) {
 
         validateNotEmpty("scopes", scopes);

src/main/java/com/microsoft/aad/msal4j/ClientSecret.java

@@ -29,20 +29,17 @@
 
 
 /**
- * Credential including secret.
+ * Representation of client credential containing a secret in string format
  */
 @EqualsAndHashCode
 public final class ClientSecret implements IClientCredential {
 
-    /**
-     * Gets the secret of the client requesting the token.
-     *
-     */
+
     @Accessors(fluent = true)
     @Getter
     private final String clientSecret;
 
-    /**
+     /**
      * Constructor to create credential with client id and secret
      *
      * @param clientSecret

src/main/java/com/microsoft/aad/msal4j/ConfidentialClientApplication.java

@@ -39,6 +39,10 @@
 
 import static com.microsoft.aad.msal4j.ParameterValidationUtils.validateNotNull;
 
+/**
+ * Class to be used to acquire tokens for confidential client applications (Web Apps, Web APIs,
+ * and daemon applications).
+ */
 public class ConfidentialClientApplication extends ClientApplicationBase implements IConfidentialClientApplication {
 
     @Override

src/main/java/com/microsoft/aad/msal4j/CredentialTypeEnum.java

@@ -31,7 +31,7 @@
 @Accessors(fluent = true)
 @Getter
 @AllArgsConstructor
-public enum CredentialTypeEnum {
+enum CredentialTypeEnum {
 
     ACCESS_TOKEN("AccessToken"),
     REFRESH_TOKEN("RefreshToken"),