feat(mtls): Rename to isAvailable() and minor comment tweaks.

Author: andyrzhao

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

@@ -38,7 +38,7 @@ public class DefaultMtlsProviderFactory {
    * Creates an instance of {@link MtlsProvider}. It first attempts to create an {@link
    * com.google.auth.mtls.X509Provider}. If the certificate source is unavailable, it falls back to
    * creating a {@link SecureConnectProvider}. If the secure connect provider also fails, it throws
-   * the original {@link com.google.auth.mtls.CertificateSourceUnavailableException}.
+   * a {@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.
@@ -49,12 +49,15 @@ public class DefaultMtlsProviderFactory {
    * @throws IOException if an I/O error occurs during provider creation.
    */
   public static MtlsProvider create() throws IOException {
+    // Note: The caller should handle CertificateSourceUnavailableException gracefully, since
+    // it is an expected error case. All other IOExceptions are unexpected and should be surfaced
+    // up the call stack.
     MtlsProvider mtlsProvider = new X509Provider();
-    if (mtlsProvider.isCertificateSourceAvailable()) {
+    if (mtlsProvider.isAvailable()) {
       return mtlsProvider;
     }
     mtlsProvider = new SecureConnectProvider();
-    if (mtlsProvider.isCertificateSourceAvailable()) {
+    if (mtlsProvider.isAvailable()) {
       return mtlsProvider;
     }
     throw new CertificateSourceUnavailableException(

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

@@ -53,10 +53,9 @@ public interface MtlsProvider {
   KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOException;
 
   /**
-   * Returns true if the underlying certificate source is available.
+   * Returns true if the underlying mTLS provider is available.
    *
-   * @throws IOException if a general I/O error occurs while determining certificate source
-   *     availability.
+   * @throws IOException if a general I/O error occurs while determining availability.
    */
-  boolean isCertificateSourceAvailable() throws IOException;
+  boolean isAvailable() throws IOException;
 }

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

@@ -105,7 +105,7 @@ public KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOEx
     try (InputStream stream = new FileInputStream(metadataPath)) {
       return getKeyStore(stream, processProvider);
     } catch (InterruptedException e) {
-      throw new IOException("Interrupted executing certificate provider command", e);
+      throw new IOException("SecureConnect: Interrupted executing certificate provider command", e);
     } catch (GeneralSecurityException e) {
       throw new CertificateSourceUnavailableException(
           "SecureConnect encountered GeneralSecurityException:", e);
@@ -117,13 +117,12 @@ public KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOEx
   }
 
   /**
-   * Returns true if the SecureConnect certificate source is available.
+   * Returns true if the SecureConnect mTLS provider is available.
    *
-   * @throws IOException if a general I/O error occurs while determining certificate source
-   *     availability
+   * @throws IOException if a general I/O error occurs while determining availability.
    */
   @Override
-  public boolean isCertificateSourceAvailable() throws IOException {
+  public boolean isAvailable() throws IOException {
     try {
       this.getKeyStore();
     } catch (CertificateSourceUnavailableException e) {
@@ -142,7 +141,8 @@ static KeyStore getKeyStore(InputStream metadata, ProcessProvider processProvide
     // so 1000 milliseconds is plenty of time.
     int exitCode = runCertificateProviderCommand(process, 1000);
     if (exitCode != 0) {
-      throw new IOException("Cert provider command failed with exit code: " + exitCode);
+      throw new IOException(
+          "SecureConnect: Cert provider command failed with exit code: " + exitCode);
     }
 
     // Create mTLS key store with the input certificates from shell command.
@@ -163,7 +163,7 @@ static int runCertificateProviderCommand(Process commandProcess, long timeoutMil
     boolean terminated = commandProcess.waitFor(timeoutMilliseconds, TimeUnit.MILLISECONDS);
     if (!terminated) {
       commandProcess.destroy();
-      throw new IOException("Cert provider command timed out");
+      throw new IOException("SecureConnect: Cert provider command timed out");
     }
     return commandProcess.exitValue();
   }

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

@@ -131,18 +131,17 @@ public KeyStore getKeyStore() throws CertificateSourceUnavailableException, IOEx
       throw e;
     } catch (Exception e) {
       // Wrap all other exception types to an IOException.
-      throw new IOException(e);
+      throw new IOException("X509Provider: Unexpected IOException:", e);
     }
   }
 
   /**
-   * Returns true if the X509 certificate source is available.
+   * Returns true if the X509 mTLS provider is available.
    *
-   * @throws IOException if a general I/O error occurs while determining certificate source
-   *     availability
+   * @throws IOException if a general I/O error occurs while determining availability.
    */
   @Override
-  public boolean isCertificateSourceAvailable() throws IOException {
+  public boolean isAvailable() throws IOException {
     try {
       this.getKeyStore();
     } catch (CertificateSourceUnavailableException e) {

oauth2_http/javatests/com/google/auth/mtls/SecureConnectProviderTest.java

@@ -113,7 +113,9 @@ public void testGetKeyStoreNonZeroExitCode()
             () -> SecureConnectProvider.getKeyStore(metadata, new TestProcessProvider(1)));
     assertTrue(
         "expected to fail with nonzero exit code",
-        actual.getMessage().contains("Cert provider command failed with exit code: 1"));
+        actual
+            .getMessage()
+            .contains("SecureConnect: Cert provider command failed with exit code: 1"));
   }
 
   @Test
@@ -142,7 +144,7 @@ public void testRunCertificateProviderCommandTimeout() throws InterruptedExcepti
             () -> SecureConnectProvider.runCertificateProviderCommand(certCommandProcess, 100));
     assertTrue(
         "expected to fail with timeout",
-        actual.getMessage().contains("Cert provider command timed out"));
+        actual.getMessage().contains("SecureConnect: Cert provider command timed out"));
   }
 
   @Test