19888 enforce explicit cause declaration in fluent exception api (#6)

* Make changes to espresso exceptions

* Refactor to two stage approach. Add test.

* Fix deprecated usages within the espresso repo. spotless.

* update readme with nexus link

* bump version

* move methods to abstract

* make methods public

Author: danielnstack8

README.md

@@ -8,7 +8,8 @@ Create your feature branch and start working. To test how the changes you are ma
 ./gradlew clean build
 ./gradlew publish
 ```
-This will publish a snapshot of the library to our internal Maven repository with the name `<version>-SNAPSHOT`
+This will publish a snapshot of the library to our internal Maven repository at https://repository.goziro.com/ with 
+the name `<version>-SNAPSHOT`
 
 You can then go to the other project, and change the version that project consumes to match your snapshot.
 

src/main/java/com/ziro/espresso/fluent/exceptions/AbstractFluentExceptionSupport.java

@@ -11,36 +11,45 @@
  * Provides fluent support to any type of throwable.
  */
 @NonNullByDefault
-public abstract class AbstractFluentExceptionSupport<T extends Throwable> {
+public abstract class AbstractFluentExceptionSupport<T extends Throwable> implements ExceptionDetailsStage<T> {
 
-    private static final String DEFAULT_EXCEPTION_MESSAGE = "Something went wrong.";
+    private static final String FALLBACK_DEFAULT_MESSAGE = "Something went wrong.";
+
+    private final String defaultMessage;
 
     @Nullable
     private String message;
 
     @Nullable
     private Throwable cause;
 
-    protected AbstractFluentExceptionSupport() {}
+    protected AbstractFluentExceptionSupport() {
+        this.defaultMessage = FALLBACK_DEFAULT_MESSAGE;
+    }
 
-    public AbstractFluentExceptionSupport<T> message(String message, Object... messageArgs) {
-        if (messageArgs.length > 0) {
-            this.message = String.format(message, messageArgs);
-        } else {
-            this.message = message;
-        }
-        return this;
+    protected AbstractFluentExceptionSupport(String defaultMessage) {
+        this.defaultMessage = defaultMessage;
     }
 
-    public AbstractFluentExceptionSupport<T> message(Supplier<String> messageSupplier) {
-        this.message = messageSupplier.get();
-        return this;
+    // Generic factory methods - to be used by concrete exception classes
+    public static <T extends Throwable> ExceptionDetailsStage<T> withCause(
+            Throwable cause, Supplier<AbstractFluentExceptionSupport<T>> builderFactory) {
+        AbstractFluentExceptionSupport<T> builder = builderFactory.get();
+        builder.setCause(cause);
+        return builder;
+    }
+
+    public static <T extends Throwable> ExceptionDetailsStage<T> asRootCause(
+            Supplier<AbstractFluentExceptionSupport<T>> builderFactory) {
+        return builderFactory.get();
     }
 
     protected Optional<String> message() {
         return Optional.ofNullable(message);
     }
 
+    // @deprecated Use withCause(Throwable) or asRootCause() instead
+    @Deprecated
     public AbstractFluentExceptionSupport<T> cause(Throwable cause) {
         this.cause = cause;
         return this;
@@ -50,20 +59,35 @@ protected Optional<Throwable> cause() {
         return Optional.ofNullable(cause);
     }
 
-    /**
-     * Throws exception if condition not satisfied.
-     * IntelliJ understands that this throws an exception, however, it does understand if the condition is null
-     * checking. Hence, you may need extra null checks to make IntelliJ happy if your condition is null checking.
-     * @throws T thrown exception.
-     */
+    @Override
+    public ExceptionDetailsStage<T> message(String message, Object... messageArgs) {
+        if (messageArgs.length > 0) {
+            this.message = String.format(message, messageArgs);
+        } else {
+            this.message = message;
+        }
+        return this;
+    }
+
+    @Override
+    public ExceptionDetailsStage<T> message(Supplier<String> messageSupplier) {
+        this.message = messageSupplier.get();
+        return this;
+    }
+
+    // Throws exception if condition not satisfied.
+    // Note: IntelliJ understands that this throws an exception but may need extra null checks for null checking
+    // conditions.
+    @Override
     public void throwIf(boolean condition) throws T {
         if (condition) {
             throw exception();
         }
     }
 
+    @Override
     public T exception() {
-        String exceptionMessage = message().orElse(DEFAULT_EXCEPTION_MESSAGE);
+        String exceptionMessage = message().orElse(defaultMessage);
         return cause().map(theCause -> {
                     if (hasSuppressedExceptions(theCause)) {
                         String exceptionMessageWithRootCause = appendRootCauseToMessage(exceptionMessage, theCause);
@@ -102,4 +126,9 @@ private static String ensureEndsWithPeriod(String exceptionMessage) {
     protected abstract T createExceptionWith(String message);
 
     protected abstract T createExceptionWith(String message, Throwable cause);
+
+    // Used by the concrete exception classes
+    void setCause(Throwable cause) {
+        this.cause = cause;
+    }
 }

src/main/java/com/ziro/espresso/fluent/exceptions/ExceptionDetailsStage.java

@@ -0,0 +1,21 @@
+package com.ziro.espresso.fluent.exceptions;
+
+import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;
+import java.util.function.Supplier;
+
+/**
+ * Second stage of the fluent exception API where message details can be set
+ * and the exception can be created or thrown.
+ * This stage is reached after explicitly choosing between withCause() or asRootCause().
+ */
+@NonNullByDefault
+public interface ExceptionDetailsStage<T extends Throwable> {
+
+    ExceptionDetailsStage<T> message(String message, Object... messageArgs);
+
+    ExceptionDetailsStage<T> message(Supplier<String> messageSupplier);
+
+    T exception();
+
+    void throwIf(boolean condition) throws T;
+}

src/main/java/com/ziro/espresso/fluent/exceptions/SystemUnhandledException.java

@@ -16,14 +16,27 @@ private SystemUnhandledException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    // Creates a new exception builder that will wrap the given cause.
+    public static ExceptionDetailsStage<SystemUnhandledException> withCause(Throwable cause) {
+        return AbstractFluentExceptionSupport.withCause(cause, SystemUnhandledExceptionBuilder::new);
+    }
+
+    // Creates a new exception builder that will be a root cause (no wrapped exception).
+    public static ExceptionDetailsStage<SystemUnhandledException> asRootCause() {
+        return AbstractFluentExceptionSupport.asRootCause(SystemUnhandledExceptionBuilder::new);
+    }
+
+    // @deprecated Use withCause(Throwable) or asRootCause() instead
+    @Deprecated
     public static AbstractFluentExceptionSupport<SystemUnhandledException> fluent() {
-        return new SystemUnhandledException.Fluent();
+        return new SystemUnhandledExceptionBuilder();
     }
 
-    private static class Fluent extends AbstractFluentExceptionSupport<SystemUnhandledException> {
+    private static class SystemUnhandledExceptionBuilder
+            extends AbstractFluentExceptionSupport<SystemUnhandledException> {
 
-        private Fluent() {
-            message(DEFAULT_MESSAGE);
+        public SystemUnhandledExceptionBuilder() {
+            super(DEFAULT_MESSAGE);
         }
 
         @Nonnull

src/main/java/com/ziro/espresso/okhttp3/JwtTokenFactory.java

@@ -41,7 +41,7 @@ public static String createAccessToken(String scope, String clientId, String cli
             ResponseBody responseBody = Objects.requireNonNull(response.body(), "responseBody should not be null");
             String responseAsString = new String(responseBody.bytes());
 
-            SystemUnhandledException.fluent()
+            SystemUnhandledException.asRootCause()
                     .message(
                             "Failed to obtain access token from Authorization Server. "
                                     + "The Authorization Server returned [status_code=%s, response=%s].",

src/main/java/com/ziro/espresso/okhttp3/OAuth2ClientAccessTokens.java

@@ -23,11 +23,10 @@ static String getAccessToken(OAuth2ClientAccessTokenRequestParameters oauth2Clie
                             oauth2ClientAccessTokenRequestParams.clientSecret(),
                             oauth2ClientAccessTokenRequestParams.tokenUrl()));
         } catch (ExecutionException e) {
-            throw SystemUnhandledException.fluent()
+            throw SystemUnhandledException.withCause(e.getCause())
                     .message(
                             "Something went wrong while trying to get access token for [%s].",
                             oauth2ClientAccessTokenRequestParams)
-                    .cause(e.getCause())
                     .exception();
         }
     }

src/main/java/com/ziro/espresso/okhttp3/OkHttpClientFactory.java

@@ -63,9 +63,8 @@ public static SSLSocketFactory buildSocketFactory(X509TrustManager trustManager)
             sslContext.init(null, trustAllCerts, new SecureRandom());
             return sslContext.getSocketFactory();
         } catch (KeyManagementException | NoSuchAlgorithmException e) {
-            throw SystemUnhandledException.fluent()
+            throw SystemUnhandledException.withCause(e)
                     .message("Something went wrong while trying to initialize all-trusting socket factory.")
-                    .cause(e)
                     .exception();
         }
     }

src/main/java/com/ziro/espresso/onepasssdk/OnePasswordConnector.java

@@ -57,12 +57,11 @@ public Properties getSecureNoteAsProperties(String vaultId, String itemId) {
         try {
             properties.load(in);
         } catch (IOException e) {
-            throw SystemUnhandledException.fluent()
+            throw SystemUnhandledException.withCause(e)
                     .message(
                             "Something went wrong while trying to load secure note as properties using "
                                     + "[vaultId=%s, itemId=%s].",
                             vaultId, itemId)
-                    .cause(e)
                     .exception();
         }
         return properties;

src/main/java/com/ziro/espresso/properties/PropertiesBuilder.java

@@ -63,9 +63,8 @@ private PropertiesBuilder load(URL url) {
         try (InputStream in = url.openStream()) {
             properties.load(in);
         } catch (Exception e) {
-            throw SystemUnhandledException.fluent()
+            throw SystemUnhandledException.withCause(e)
                     .message("Something went wrong while trying to load properties from [url=%s]", url)
-                    .cause(e)
                     .exception();
         }
         return this;
@@ -83,7 +82,7 @@ private static URL toUrl(File file) {
         try {
             return file.toURI().toURL();
         } catch (MalformedURLException e) {
-            throw SystemUnhandledException.fluent()
+            throw SystemUnhandledException.withCause(e)
                     .message("Something went wrong while trying to convert file [name=%s] to URL.", file.getName())
                     .exception();
         }

src/test/java/com/ziro/espresso/fluent/exceptions/SystemUnhandledExceptionTest.java

@@ -0,0 +1,73 @@
+package com.ziro.espresso.fluent.exceptions;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.junit.jupiter.api.Test;
+
+class SystemUnhandledExceptionTest {
+
+    @Test
+    void whenUsingWithCauseThenExceptionWrapsOriginalCause() {
+        RuntimeException originalCause = new RuntimeException("Original error");
+
+        SystemUnhandledException exception = SystemUnhandledException.withCause(originalCause)
+                .message("Something went wrong")
+                .exception();
+
+        assertThat(exception.getMessage()).isEqualTo("Something went wrong");
+        assertThat(exception.getCause()).isEqualTo(originalCause);
+    }
+
+    @Test
+    void whenUsingAsRootCauseThenExceptionHasNoCause() {
+        SystemUnhandledException exception = SystemUnhandledException.asRootCause()
+                .message("Something went wrong")
+                .exception();
+
+        assertThat(exception.getMessage()).isEqualTo("Something went wrong");
+        assertThat(exception.getCause()).isNull();
+    }
+
+    @Test
+    void whenUsingWithCauseAndThrowIfThenThrowsExceptionWhenConditionTrue() {
+        RuntimeException originalCause = new RuntimeException("Original error");
+
+        assertThatThrownBy(() -> {
+                    SystemUnhandledException.withCause(originalCause)
+                            .message("Something went wrong")
+                            .throwIf(true);
+                })
+                .isInstanceOf(SystemUnhandledException.class)
+                .hasMessage("Something went wrong")
+                .hasCause(originalCause);
+    }
+
+    @Test
+    void whenUsingMessageWithFormatting_thenFormatsCorrectly() {
+        SystemUnhandledException exception = SystemUnhandledException.asRootCause()
+                .message("Error processing %s with value %d", "item", 42)
+                .exception();
+
+        assertThat(exception.getMessage()).isEqualTo("Error processing item with value 42");
+    }
+
+    @Test
+    void whenNoMessageProvidedThenUsesDefaultMessage() {
+        SystemUnhandledException exception =
+                SystemUnhandledException.asRootCause().exception();
+
+        assertThat(exception.getMessage()).isEqualTo(SystemUnhandledException.DEFAULT_MESSAGE);
+    }
+
+    @Test
+    void whenNoMessageProvidedWithCauseThenUsesDefaultMessage() {
+        RuntimeException originalCause = new RuntimeException("Original error");
+
+        SystemUnhandledException exception =
+                SystemUnhandledException.withCause(originalCause).exception();
+
+        assertThat(exception.getMessage()).isEqualTo(SystemUnhandledException.DEFAULT_MESSAGE);
+        assertThat(exception.getCause()).isEqualTo(originalCause);
+    }
+}