Merge pull request #124 from mmusgrov/issue122

issue122 Clarify LRA context on @Leave methods

api/src/main/java/org/eclipse/microprofile/lra/annotation/Compensate.java

@@ -27,12 +27,23 @@
 import java.time.temporal.ChronoUnit;
 
 /**
- * When a bean method executes in the context of an LRA any methods in the bean
- * class that are annotated with @Compensate will be used as a participant for
- * that LRA. If it is applied to multiple methods an arbitrary one is chosen.
+ * When a resource method executes in the context of an LRA and if the containing
+ * class contains a method annotated with `@Compensate` then the resource will
+ * be used as a participant for the LRA. If this associated LRA is subsequently
+ * cancelled then the method that this annotation is applied to will be invoked
+ * (if the annotation is present on more than one method then an arbitrary one
+ * will be chosen).
  *
- * If the associated LRA is subsequently cancelled the method on which this
- * annotation is present will be invoked.
+ * The id of the currently running LRA can be obtained by inspecting the incoming
+ * JAX-RS headers.
+ *
+ * Note that, according to the state model {@link LRAStatus} once an LRA has been
+ * asked to cancel it is no longer possible to join with it as a participant.
+ * Therefore combining this annotation with an `@LRA` annotation that does not
+ * start a new LRA will result in a `412 PreCondition Failed` status code and is
+ * not advised. On the other hand, combining it with an `@LRA` annotation that
+ * begins a new LRA can in certain use case make sense, but in this case the LRA
+ * that this method is being asked to compensate for will be unavailable.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD})

api/src/main/java/org/eclipse/microprofile/lra/annotation/Complete.java

@@ -27,12 +27,23 @@
 import java.time.temporal.ChronoUnit;
 
 /**
- * When a bean method executes in the context of an LRA any methods in the bean
- * class that are annotated with @Complete will be used as a participant for
- * that LRA. If it is applied to multiple methods an arbitrary one is chosen.
+ * When a resource method executes in the context of an LRA and if the containing
+ * class contains a method annotated with `@Complete` then the resource will
+ * be used as a participant for the LRA. If this associated LRA is subsequently
+ * closed then the method that this annotation is applied to will be invoked
+ * (if the annotation is present on more than one method then an arbitrary one
+ * will be chosen).
  *
- * If the associated LRA is subsequently closed the method on which this
- * annotation is present will be invoked.
+ * The id of the currently running LRA can be obtained by inspecting the incoming
+ * JAX-RS headers.
+ *
+ * Note that, according to the state model {@link LRAStatus} once an LRA has been
+ * asked to close it is no longer possible to join with it as a participant.
+ * Therefore combining this annotation with an `@LRA` annotation that does not
+ * start a new LRA will result in a `412 PreCondition Failed` status code and is
+ * not advised. On the other hand, combining it with an `@LRA` annotation that
+ * begins a new LRA can in certain use case make sense, but in this case the LRA
+ * that this method is being asked to complete for will be unavailable.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD})

api/src/main/java/org/eclipse/microprofile/lra/annotation/Forget.java

@@ -35,6 +35,13 @@
  * must be a standard JAX-RS endpoint annotated with the JAX-RS
  * <em>@DELETE</em> annotation.
  *
+ * The id of the currently running LRA can be obtained by inspecting the
+ * incoming JAX-RS headers.
+ *
+ * Since the participant generally needs to know the id of the LRA in order
+ * to clean up there is generally no benefit to combining this annotation
+ * with the `@LRA` annotation (though it is not prohibited).
+ *
  * Related information is provided in the javadoc for the {@link Status}
  */
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/org/eclipse/microprofile/lra/annotation/LRAStatus.java

@@ -24,7 +24,7 @@
  * A representation of the status of a Long Running Action according to a
  * LRA state model:
  *
- * The initial state Active is entered when a LRA is created.
+ * The initial state Active is entered when an LRA is created.
  *
  * The state Cancelling is entered when a request to cancel
  * an LRA is received. The transition to end state Cancelled

api/src/main/java/org/eclipse/microprofile/lra/annotation/Status.java

@@ -27,7 +27,7 @@
 import java.lang.annotation.Target;
 
 /**
- * LRA annoations support distributed communications amongst software
+ * LRA annotations support distributed communications amongst software
  * components and due to the unreliable nature of networks,
  * messages/requests can be lost, delayed or duplicated etc and the
  * implementation component responsible for invoking {@link Compensate}
@@ -53,6 +53,13 @@
  * status code (such as
  * {@link org.eclipse.microprofile.lra.client.IllegalLRAStateException}
  * but any exception that maps to 412 will do).
+ *
+ * The id of the currently running LRA can be obtained by inspecting the
+ * incoming JAX-RS headers.
+ *
+ * Since the participant generally needs to know the id of the LRA in order
+ * to report its status there is generally no benefit to combining this
+ * annotation with the `@LRA` annotation (though it is not prohibited).
  */
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/org/eclipse/microprofile/lra/annotation/ws/rs/LRA.java

@@ -64,7 +64,8 @@
  *
  * <p>
  * If an LRA is propagated to a resource that is not annotated with any
- * particular LRA behaviour then the LRA will be suspended. But if this resource
+ * particular LRA behaviour then the LRA will be suspended (ie the context
+ * will not be available to the resource). But if this resource
  * then performs an outgoing JAX-RS request then the suspended LRA must be propagated
  * on this second outgoing request. For example, suppose resource <code>A</code> starts an LRA
  * and then performs a JAX-RS request to resource <code>B</code> which does not contain any LRA
@@ -75,8 +76,9 @@
  * </p>
  *
  * <p>
- * Resource methods can access the LRA context id, if required, by injecting it via
- * the JAX-RS {@link HeaderParam} annotation. This may be useful, for example, for
+ * Resource methods can access the LRA context id, if required, by inspecting the request headers
+ * using standard JAX-RS mechanisms, ie `@Context` or by injecting it via the JAX-RS {@link HeaderParam}
+ * annotation with value {@value #LRA_HTTP_HEADER}. This may be useful, for example, for
  * associating business work with an LRA.
  * </p>
  */
@@ -100,7 +102,7 @@
     /**
      * <p>
      * The Type element of the LRA annotation indicates whether a bean method
-     * is to be executed within the context of a LRA.
+     * is to be executed within the context of an LRA.
      *
      * <p>
      * If the method is to run in the context of an LRA and the annotated class
@@ -136,13 +138,13 @@
     enum Type {
         /**
          * <p>
-         * If called outside a LRA context a new LRA will be created for the
+         * If called outside an LRA context a new LRA will be created for the
          * the duration of the method call and when the call completes it will
          * be closed.
          * </p>
          *
          * <p>
-         * If called inside a LRA context the invoked method will run with the
+         * If called inside an LRA context the invoked method will run with the
          * same context and the context will remain active after the method
          * completes.
          * </p>
@@ -151,13 +153,13 @@ enum Type {
 
         /**
          * <p>
-         * If called outside a LRA context a new LRA will be created for the
+         * If called outside an LRA context a new LRA will be created for the
          * the duration of the method call and when the call completes it will
          * be terminated (closed or cancelled).
          * </p>
          *
          * <p>
-         * If called inside a LRA context it will be suspended and a new LRA
+         * If called inside an LRA context it will be suspended and a new LRA
          * context will be created for the duration of the call. When the method
          * finishes this new LRA will be terminated (closed or cancelled) and
          * the original context will be resumed.
@@ -187,32 +189,32 @@ enum Type {
 
         /**
          *  <p>
-         *  If called outside a LRA context the bean method execution
-         *  must then continue outside a LRA context.
+         *  If called outside an LRA context the bean method execution
+         *  must then continue outside an LRA context.
          *  </p>
          *
          *  <p>
-         *  If called inside a LRA context the managed bean method execution
+         *  If called inside an LRA context the managed bean method execution
          *  must then continue inside this LRA context.
          *  </p>
          */
         SUPPORTS,
 
         /**
-         * The bean method is executed without a LRA context. If a context is
+         * The bean method is executed without an LRA context. If a context is
          * present on entry then it is suspended and then resumed after the
          * execution has completed.
          */
         NOT_SUPPORTED,
 
         /**
          * <p>
-         * If called outside a LRA context the managed bean method execution
-         * must then continue outside a LRA context.
+         * If called outside an LRA context the managed bean method execution
+         * must then continue outside an LRA context.
          * </p>
          *
          * <p>
-         * If called inside a LRA context the method is not executed and a
+         * If called inside an LRA context the method is not executed and a
          * <code>412 Precondition Failed</code> HTTP status code is returned
          * to the caller.
          * </p>

api/src/main/java/org/eclipse/microprofile/lra/annotation/ws/rs/Leave.java

@@ -26,22 +26,42 @@
 import java.lang.annotation.Target;
 
 /**
- * A resource may be enlisted with an LRA if one of its resource methods
- * annotated with @LRA is invoked. If the resource also contains a method
- * annotated with @Leave, then invoking such a method in the context of the
- * same LRA that it has joined will result in the resource leaving the LRA
- * (ie it will not receive any callbacks when the LRA is later closed or
- * cancelled). However, leaving an LRA does not prohibit the resource from
- * rejoining the LRA if one of the @LRA methods is invoked again in the
- * context of the same LRA.
+ * <p>
+ * If a resource method is annotated with `@Leave` and is invoked in the context of
+ * an LRA and if the bean class has registered a participant with that LRA then
+ * it will be removed from the LRA just before the bean method is entered.
+ * The participant can forget about this LRA, in particular it will not
+ * be asked to complete or compensate when the LRA is subsequently ended.
+ * Even though the method runs without an LRA context, the implementation
+ * MUST still make the context available via a JAX-RS header and any outgoing
+ * JAX-RS invocations performed by the method will still carry the context that
+ * the participant has just left. Therefore the business logic must be
+ * careful about any JAX-RS invocations it makes in the body of the annotated
+ * method which may result in other resources being enlisted with the LRA.
+ * </p>
  *
- * Note that it is not possible to join or leave an LRA that has already
- * been asked to cancel or close.
+ * <p>
+ * If the resource method (or class) is also annotated with `@LRA` the method will
+ * execute with the context dictated by the `@LRA` annotation. If this `@LRA` annotation
+ * results in the creation of a new LRA then the participant will still be removed
+ * from the incoming context and will be enlisted with the new context (and the method
+ * will execute with this new context). Note that in this case the context exposed in
+ * the `LRA_HTTP_HEADER` JAX-RS header will be set to the new LRA (and not the original
+ * one), ie the orignal context will not be available to the business logic.
+ * </p>
  *
+ * <p>
+ * Also note that it is not possible to join or leave an LRA that has already
+ * been asked to cancel or close (since that would conflict with the
+ * the participant state model as defined in the LRA specification).
+ * </p>
+ *
+ * <p>
  * Leaving a particular LRA has no effect on any other LRA - ie the same
- * resource can be enlisted with many different LRA's and leaving one
+ * resource can be enlisted with many different LRAs and leaving one
  * particular LRA will not affect its participation in any of the other
  * LRA's it has joined.
+ * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD})

api/src/main/java/org/eclipse/microprofile/lra/annotation/ws/rs/NestedLRA.java

@@ -49,9 +49,9 @@
  *   <li>SUPPORTS if there is an LRA present a new LRA is nested under otherwise
  *   a new top level LRA is begun
  *   <li>NOT_SUPPORTED nested does not make sense and operations on this resource
- *   that contain a LRA context will immediately return with a
+ *   that contain an LRA context will immediately return with a
  *   <code>412 Precondition Failed</code> HTTP status code
- *   <li>NEVER nested does not make sense and requests that carry a LRA context
+ *   <li>NEVER nested does not make sense and requests that carry an LRA context
  *   will immediately return with a <code>412 Precondition Failed</code> HTTP
  *   status code
  * </ul>