Merge pull request #616 from Ladicek/jakarta-update

Bring the 'jakarta' branch up to date with tag '5.4.0'

.github/workflows/build.yml

@@ -30,8 +30,8 @@ jobs:
         - 8
         - 11
         - 17
-        # Temurin doesn't have an 18-ea build yet
-        #- 18-ea
+        - 18
+        - 19-ea
         os:
         - ubuntu-latest
         - windows-latest

api/pom.xml

@@ -32,6 +32,10 @@
             <groupId>jakarta.enterprise</groupId>
             <artifactId>jakarta.enterprise.cdi-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.eclipse.microprofile.fault-tolerance</groupId>
+            <artifactId>microprofile-fault-tolerance-api</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.smallrye.common</groupId>
             <artifactId>smallrye-common-annotation</artifactId>

api/src/main/java/io/smallrye/faulttolerance/api/ApplyFaultTolerance.java

@@ -0,0 +1,61 @@
+package io.smallrye.faulttolerance.api;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import jakarta.interceptor.InterceptorBinding;
+
+import io.smallrye.common.annotation.Experimental;
+
+/**
+ * A special interceptor binding annotation to apply preconfigured fault tolerance.
+ * If {@code @ApplyFaultTolerance("<identifier>")} is present on a business method,
+ * then a bean of type {@link FaultTolerance} with qualifier
+ * {@link io.smallrye.common.annotation.Identifier @Identifier("<identifier>")}
+ * must exist. Such bean serves as a preconfigured set of fault tolerance strategies
+ * and is used to guard invocations of the annotated business method(s).
+ * <p>
+ * It is customary to create such bean by declaring a {@code static} producer field.
+ * That removes all scoping concerns, because only one instance ever exists. Using
+ * a non-static producer field or a producer method means that scoping must be carefully
+ * considered, especially if stateful fault tolerance strategies are configured.
+ * <p>
+ * The {@code @ApplyFaultTolerance} annotation may also be present on a bean class,
+ * in which case it applies to all business methods declared by the class. If the
+ * annotation is present both on the method and the class declaring the method,
+ * the one on the method takes precedence.
+ * <p>
+ * When {@code @ApplyFaultTolerance} applies to a business method, all other fault tolerance
+ * annotations that would otherwise also apply to that method are ignored.
+ * <p>
+ * A single preconfigured fault tolerance can be applied to multiple methods, as long as asynchrony
+ * of all those methods is the same as the asynchrony of the fault tolerance instance. For example,
+ * if the fault tolerance instance is created using {@code FaultTolerance.create()}, it can be
+ * applied to all synchronous methods, but not to any asynchronous method. If the fault tolerance
+ * instance is created using {@code FaultTolerance.createAsync()}, it can be applied to all
+ * asynchronous methods that return {@code CompletionStage}, but not to synchronous methods or
+ * asynchronous methods that return any other asynchronous type.
+ * <p>
+ * A single preconfigured fault tolerance can even be applied to multiple methods with different
+ * return types, as long as the constraint on method asynchrony described above is obeyed. In such
+ * case, it is customary to declare the fault tolerance instance as {@code FaultTolerance&lt;Object>}
+ * for synchronous methods, {@code FaultTolerance&lt;CompletionStage&lt;Object>>} for asynchronous
+ * methods that return {@code CompletionStage}, and so on. Note that this effectively precludes
+ * defining a useful fallback, because fallback can only be defined when the value type is known.
+ */
+@Inherited
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.TYPE })
+@InterceptorBinding
+@Experimental("first attempt at providing reusable fault tolerance strategies")
+public @interface ApplyFaultTolerance {
+    /**
+     * The identifier of a preconfigured fault tolerance instance.
+     */
+    String value();
+}

api/src/main/java/io/smallrye/faulttolerance/api/CircuitBreakerMaintenance.java

@@ -15,11 +15,14 @@
  */
 package io.smallrye.faulttolerance.api;
 
+import java.util.function.Consumer;
+
 import io.smallrye.common.annotation.Experimental;
 
 /**
- * Allows reading current state of circuit breakers and reseting them to the initial (closed) state.
- * To access a specific circuit breaker, it must be given a name using {@link CircuitBreakerName @CircuitBreakerName}.
+ * Allows reading and observing current state of circuit breakers and reseting them to the initial (closed) state.
+ * To access a specific circuit breaker, it must be given a name using {@link CircuitBreakerName @CircuitBreakerName}
+ * or {@link FaultTolerance.Builder.CircuitBreakerBuilder#name(String) withCircuitBreaker().name("...")}.
  */
 @Experimental("first attempt at providing maintenance access to circuit breakers")
 public interface CircuitBreakerMaintenance {
@@ -28,22 +31,37 @@ public interface CircuitBreakerMaintenance {
      * Note that there's no guarantee that the circuit breaker will stay in that state for any time,
      * so this method is only useful for monitoring.
      * <p>
-     * It is an error to use a {@code name} that wasn't registered using {@code @CircuitBreakerName}.
+     * It is an error to use a {@code name} that wasn't registered using {@link CircuitBreakerName @CircuitBreakerName}
+     * or {@link FaultTolerance.Builder.CircuitBreakerBuilder#name(String) withCircuitBreaker().name("...")}.
      */
     CircuitBreakerState currentState(String name);
 
+    /**
+     * Registers a {@code callback} to be called when the circuit breaker with given {@code name}
+     * changes state.
+     * <p>
+     * It is an error to use a {@code name} that wasn't registered using {@link CircuitBreakerName @CircuitBreakerName}
+     * or {@link FaultTolerance.Builder.CircuitBreakerBuilder#name(String) withCircuitBreaker().name("...")}.
+     * <p>
+     * The callback must be fast and non-blocking and must not throw an exception.
+     */
+    void onStateChange(String name, Consumer<CircuitBreakerState> callback);
+
     /**
      * Resets the circuit breaker with given {@code name} to the initial (closed) state.
      * <p>
      * This method should not be used regularly, it's mainly meant for testing (to isolate individual tests)
      * and perhaps emergency maintenance tasks.
      * <p>
-     * It is an error to use a {@code name} that wasn't registered using {@code @CircuitBreakerName}.
+     * It is an error to use a {@code name} that wasn't registered using {@link CircuitBreakerName @CircuitBreakerName}
+     * or {@link FaultTolerance.Builder.CircuitBreakerBuilder#name(String) withCircuitBreaker().name("...")}.
      */
     void reset(String name);
 
     /**
-     * Resets all circuit breakers (including those without a name) in the application to the initial (closed) state.
+     * Resets all circuit breakers in the application to the initial (closed) state.
+     * This includes all named circuit breakers and unnamed circuit breakers declared using {@code @CircuitBreaker}.
+     * It does <em>not</em> include unnamed circuit breakers created using the programmatic API.
      * <p>
      * This method should not be used regularly, it's mainly meant for testing (to isolate individual tests)
      * and perhaps emergency maintenance tasks.