feat(mtls): Update Java docs.

Author: andyrzhao

oauth2_http/java/com/google/auth/mtls/ContextAwareMetadataJson.java

@@ -35,7 +35,14 @@
 import com.google.common.collect.ImmutableList;
 import java.util.List;
 
-/** Data class representing context_aware_metadata.json file. */
+/**
+ * Data class representing context_aware_metadata.json file. This is meant for internal Google Cloud
+ * usage and behavior may be changed without warning.
+ *
+ * <p>Note: This implementation is duplicated from the existing ContextAwareMetadataJson found in
+ * the Gax library. The Gax library version of ContextAwareMetadataJson will be marked as deprecated
+ * in the future.
+ */
 public class ContextAwareMetadataJson extends GenericJson {
   /** Cert provider command */
   @Key("cert_provider_command")

oauth2_http/java/com/google/auth/mtls/DefaultMtlsProviderFactory.java

@@ -40,6 +40,9 @@ public class DefaultMtlsProviderFactory {
    * creating a {@link SecureConnectProvider}. If the secure connect provider also fails, it throws
    * the original {@link com.google.auth.mtls.CertificateSourceUnavailableException}.
    *
+   * <p>This is only meant to be used internally by Google Cloud libraries, and the public facing
+   * methods may be changed without notice, and have no guarantee of backwards compatibility.
+   *
    * @return an instance of {@link MtlsProvider}.
    * @throws com.google.auth.mtls.CertificateSourceUnavailableException if neither provider can be
    *     created.

oauth2_http/java/com/google/auth/mtls/MtlsProvider.java

@@ -42,9 +42,21 @@
  * https://github.com/googleapis/google-auth-library-java/issues/1758
  */
 public interface MtlsProvider {
-  /** Returns the mutual TLS key store. */
-  KeyStore getKeyStore() throws IOException;
+  /**
+   * Returns a mutual TLS key store.
+   *
+   * @return KeyStore for configuring mTLS.
+   * @throws CertificateSourceUnavailableException if the certificate source is unavailable (ex.
+   *     missing configuration file).
+   * @throws IOException if a general I/O error occurs while creating the KeyStore
+   */
+  KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOException;
 
-  /** Returns true if the underlying certificate source is available. */
+  /**
+   * Returns true if the underlying certificate source is available.
+   *
+   * @throws IOException if a general I/O error occurs while determining certificate source
+   *     availability.
+   */
   boolean isCertificateSourceAvailable() throws IOException;
 }

oauth2_http/java/com/google/auth/mtls/SecureConnectProvider.java

@@ -48,7 +48,7 @@
  * This class implements {@link MtlsProvider} for the Google Auth library transport layer via {@link
  * ContextAwareMetadataJson}. This is only meant to be used internally by Google Cloud libraries,
  * and the public facing methods may be changed without notice, and have no guarantee of backwards
- * compatability.
+ * compatibility.
  *
  * <p>Note: This implementation is derived from the existing "MtlsProvider" found in the Gax
  * library, with two notable differences: 1) All logic associated with parsing environment variables
@@ -92,9 +92,16 @@ public SecureConnectProvider() {
     this(new DefaultProcessProvider(), DEFAULT_CONTEXT_AWARE_METADATA_PATH);
   }
 
-  /** The mutual TLS key store created with the default client certificate on device. */
+  /**
+   * Returns a mutual TLS key store backed by the certificate provided by the SecureConnect tool.
+   *
+   * @return a KeyStore containing the certificate provided by the SecureConnect tool.
+   * @throws CertificateSourceUnavailableException if the certificate source is unavailable (ex.
+   *     missing configuration file).
+   * @throws IOException if a general I/O error occurs while creating the KeyStore.
+   */
   @Override
-  public KeyStore getKeyStore() throws IOException {
+  public KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOException {
     try (InputStream stream = new FileInputStream(metadataPath)) {
       return getKeyStore(stream, processProvider);
     } catch (InterruptedException e) {
@@ -109,6 +116,12 @@ public KeyStore getKeyStore() throws IOException {
     }
   }
 
+  /**
+   * Returns true if the SecureConnect certificate source is available.
+   *
+   * @throws IOException if a general I/O error occurs while determining certificate source
+   *     availability
+   */
   @Override
   public boolean isCertificateSourceAvailable() throws IOException {
     try {

oauth2_http/java/com/google/auth/mtls/X509Provider.java

@@ -45,7 +45,7 @@
  * This class implements {@link MtlsProvider} for the Google Auth library transport layer via {@link
  * WorkloadCertificateConfiguration}. This is only meant to be used internally by Google Cloud
  * libraries, and the public facing methods may be changed without notice, and have no guarantee of
- * backwards compatability.
+ * backwards compatibility.
  */
 public class X509Provider implements MtlsProvider {
   static final String CERTIFICATE_CONFIGURATION_ENV_VARIABLE = "GOOGLE_API_CERTIFICATE_CONFIG";
@@ -109,10 +109,12 @@ public String getCertificatePath() throws IOException {
    * </ul>
    *
    * @return a KeyStore containing the X.509 certificate specified by the certificate configuration.
-   * @throws IOException if there is an error retrieving the certificate configuration.
+   * @throws CertificateSourceUnavailableException if the certificate source is unavailable (ex.
+   *     missing configuration file)
+   * @throws IOException if a general I/O error occurs while creating the KeyStore
    */
   @Override
-  public KeyStore getKeyStore() throws IOException {
+  public KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOException {
     WorkloadCertificateConfiguration workloadCertConfig = getWorkloadCertificateConfiguration();
 
     // Read the certificate and private key file paths into streams.
@@ -133,6 +135,12 @@ public KeyStore getKeyStore() throws IOException {
     }
   }
 
+  /**
+   * Returns true if the X509 certificate source is available.
+   *
+   * @throws IOException if a general I/O error occurs while determining certificate source
+   *     availability
+   */
   @Override
   public boolean isCertificateSourceAvailable() throws IOException {
     try {