issue35 Adjust javadoc to reflect new participant methods definitions

Signed-off-by: xstefank <[email protected]>

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

@@ -35,11 +35,24 @@
  * will be chosen). The spec makes no guarantees about when it will be invoked,
  * just that is will eventually be called.
  *
- * The id of the currently running LRA can be obtained by inspecting the incoming
- * JAX-RS headers. If this LRA is nested then the parent LRA MUST be present
- * in the header with the name
+ * If the annotated method is a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by inspecting the incoming JAX-RS headers. If
+ * this LRA is nested then the parent LRA MUST be present in the header with the name
  * {@link org.eclipse.microprofile.lra.annotation.ws.rs.LRA#LRA_HTTP_PARENT_CONTEXT_HEADER}.
  *
+ * If the annotated method is not a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by adhering to a predefined method signature as
+ * defined in the LRA specification document. Similarly the method may determine
+ * whether or not it runs with a nested LRA by providing a parameter to hold the parent id.
+ * For example,
+ * <pre>
+ *     <code>
+ *          &#64;Compensate
+ *          public void compensate(URI lraId, URI parentId) { ...}
+ *     </code>
+ * </pre>
+ * would be a valid compensation method declaration.
+ *
  * 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

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

@@ -37,11 +37,25 @@
  * If the annotation is present on more than one method then an arbitrary one
  * will be chosen.
  *
- * The id of the currently running LRA can be obtained by inspecting the incoming
- * JAX-RS headers. If this LRA is nested then the parent LRA MUST be present
- * in the header with the name
+ * If the annotated method is a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by inspecting the incoming JAX-RS headers. If
+ * this LRA is nested then the parent LRA MUST be present in the header with the name
  * {@link org.eclipse.microprofile.lra.annotation.ws.rs.LRA#LRA_HTTP_PARENT_CONTEXT_HEADER}.
  *
+ * If the annotated method is not a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by adhering to a predefined method signature as
+ * defined in the LRA specification document. Similarly the method may determine
+ * whether or not it runs with a nested LRA by providing a parameter to hold the parent id.
+ * For example,
+ * <pre>
+ *     <code>
+ *          &#64;Complete
+ *          public void complete(URI lraId, URI parentId) { ...}
+ *     </code>
+ * </pre>
+ * would be a valid completion method declaration.
+ *
+ *
  * 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

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

@@ -33,21 +33,33 @@
  * in progress) or because of a failure (ie will never be able to finish)
  * then it must remember the fact (by reporting it when asked for its'
  * {@link Status})) until explicitly told that it can clean
- * up using this <em>@Forget</em> annotation. The annotated method
- * must be a standard JAX-RS endpoint annotated with the JAX-RS
- * <em>@DELETE</em> annotation.
+ * up using this <em>@Forget</em> annotation.
  *
  * A similar remark applies if the participant was enlisted in a
  * nested LRA {@link LRA#value()}. Actions performed in the context
  * of a nested LRA must remain compensatable until the participant
  * is explicitly told it can clean up using this <em>@Forget</em>
  * annotation.
  *
- * The id of the currently running LRA can be obtained by inspecting the
- * incoming JAX-RS headers. If this LRA is nested then the parent LRA
- * MUST be present in the header with the name
+ * If the annotated method is a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by inspecting the incoming JAX-RS headers. If
+ * this LRA is nested then the parent LRA MUST be present in the header with the name
  * {@link org.eclipse.microprofile.lra.annotation.ws.rs.LRA#LRA_HTTP_PARENT_CONTEXT_HEADER}.
  *
+ * If the annotated method is not a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by adhering to a predefined method signature as
+ * defined in the LRA specification document. Similarly the method may determine
+ * whether or not it runs with a nested LRA by providing a parameter to hold the parent id.
+ * For example,
+ * <pre>
+ *     <code>
+ *          &#64;Forget
+ *          public void forget(URI lraId, URI parentId) { ...}
+ *     </code>
+ * </pre>
+ * would be a valid forget method declaration.
+ *
+ *
  * 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).

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

@@ -36,18 +36,33 @@
  * or compensation notification but if the participant (the class that
  * contains the Compensate and Complete annotations) does not
  * support idempotency then it must be able to report its' status by
- * by annotating one of the methods with this <em>@Status</em> annotation
- * together with the <em>@GET</em> JAX-RS annotation.
+ * by annotating one of the methods with this <em>@Status</em>.
  * The annotated method should report the status according to one of the
  * {@link ParticipantStatus} enum values.
  *
+ * If the annotated method is a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by inspecting the incoming JAX-RS headers. If
+ * this LRA is nested then the parent LRA MUST be present in the header with the name
+ * {@link org.eclipse.microprofile.lra.annotation.ws.rs.LRA#LRA_HTTP_PARENT_CONTEXT_HEADER}.
+ *
+ * If the annotated method is not a JAX-RS resource method the id of the currently
+ * running LRA can be obtained by adhering to a predefined method signature as
+ * defined in the LRA specification document. Similarly the method may determine
+ * whether or not it runs with a nested LRA by providing a parameter to hold the parent id.
+ * For example,
+ * <pre>
+ *     <code>
+ *          &#64;Status
+ *          public void status(URI lraId, URI parentId) { ...}
+ *     </code>
+ * </pre>
+ * would be a valid status method declaration.
+ *
  * If the participant has already responded successfully to an invocation
  * of the <em>@Compensate</em> or <em>@Complete</em> method then it may
- * report <em>404 Not Found</em> HTTP status code. This enables the
- * participant to free up resources.
- *
- * The id of the currently running LRA can be obtained by inspecting the
- * incoming JAX-RS headers.
+ * report <em>404 Not Found</em> HTTP status code or in case of 
+ * non-JAX-RS method to return <em>null</em>. 
+ * This enables the participant to free up resources.
  *
  * 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

api/src/main/java/org/eclipse/microprofile/lra/participant/InvalidLRAParticipantDefinitionException.java

@@ -20,7 +20,7 @@
 package org.eclipse.microprofile.lra.participant;
 
 /**
- * Runtime exception thrown when nonjaxrs LRA nonjaxrs definition is detected
+ * Runtime exception thrown when invalid non-JAX-RS LRA signature definition is detected
  */
 public class InvalidLRAParticipantDefinitionException extends RuntimeException {
 

tck/src/main/java/org/eclipse/microprofile/lra/tck/TckInvalidParticipantSignaturesTests.java

@@ -38,7 +38,17 @@
 import org.junit.rules.TestName;
 import org.junit.runner.RunWith;
 
-
+/**
+ * <p>
+ * TCK that verifies that invalid non-JAX-RS participant method signatures are reported during deployment
+ * </p>
+ * 
+ * <p>
+ * Each test deploys an archive containing single invalid participant containing an error in its participant 
+ * method signature and expects that such deployment is aborted with {@link InvalidLRAParticipantDefinitionException} 
+ * according to the specification.
+ * </p>
+ */
 @RunWith(Arquillian.class)
 public class TckInvalidParticipantSignaturesTests {
 

tck/src/main/java/org/eclipse/microprofile/lra/tck/TckParticipantTests.java

@@ -31,7 +31,9 @@
 
 import static org.junit.Assert.assertEquals;
 
-
+/**
+ * TCK to verify that valid non-JAX-RS participant method signatures are respected
+ */
 @RunWith(Arquillian.class)
 public class TckParticipantTests extends TckTestBase {
 

tck/src/main/java/org/eclipse/microprofile/lra/tck/participant/nonjaxrs/InvalidArgumentTypesParticipant.java

@@ -30,6 +30,9 @@
 import javax.ws.rs.core.Response;
 import java.net.URI;
 
+/**
+ * TCK invalid LRA participant containing invalid type of arguments in the participant method signature
+ */
 @ApplicationScoped
 @Path("nonjaxrs-argument-type-nonjaxrs")
 public class InvalidArgumentTypesParticipant {

tck/src/main/java/org/eclipse/microprofile/lra/tck/participant/nonjaxrs/InvalidReturnTypeParticipant.java

@@ -27,6 +27,9 @@
 import javax.ws.rs.Path;
 import javax.ws.rs.core.Response;
 
+/**
+ * TCK invalid LRA participant containing invalid return type in the participant method signature
+ */
 @ApplicationScoped
 @Path("nonjaxrs-return-type")
 public class InvalidReturnTypeParticipant {

tck/src/main/java/org/eclipse/microprofile/lra/tck/participant/nonjaxrs/TooManyArgsParticipant.java

@@ -30,6 +30,9 @@
 import javax.ws.rs.core.Response;
 import java.net.URI;
 
+/**
+ * TCK invalid LRA participant containing too many arguments in the participant method signature
+ */
 @ApplicationScoped
 @Path("too-many-args-nonjaxrs")
 public class TooManyArgsParticipant {

tck/src/main/java/org/eclipse/microprofile/lra/tck/participant/nonjaxrs/ValidLRAParticipant.java

@@ -44,6 +44,9 @@
 import static org.eclipse.microprofile.lra.tck.participant.api.ParticipatingTckResource.ACCEPT_PATH;
 import static org.eclipse.microprofile.lra.tck.participant.api.ParticipatingTckResource.RECOVERY_PARAM;
 
+/**
+ * TCK valid LRA participant containing a combination of valid participant method signatures
+ */
 @ApplicationScoped
 @Path(ValidLRAParticipant.RESOURCE_PATH)
 public class ValidLRAParticipant {