Merge pull request #148 from xstefank/issue35

issue35 Do not define JAX-RS annotations on @compensate methods

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

@@ -35,14 +35,29 @@
  * 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. If an invalid signature is detected 
+ * the {@link org.eclipse.microprofile.lra.participant.InvalidLRAParticipantDefinitionException} 
+ * will be thrown during the application startup.
+ *
  * 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
+ * Therefore in JAX-RS, 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

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

@@ -37,14 +37,29 @@
  * 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. If an invalid signature is detected 
+ * the {@link org.eclipse.microprofile.lra.participant.InvalidLRAParticipantDefinitionException} 
+ * will be thrown during the application startup.
+ *
  * 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
+ * Therefore in JAX-RS, 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

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

@@ -33,21 +33,35 @@
  * 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. If an invalid signature is detected 
+ * the {@link org.eclipse.microprofile.lra.participant.InvalidLRAParticipantDefinitionException} 
+ * will be thrown during the application startup.
+ *
+ *
  * 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,35 @@
  * 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 an invalid signature is detected 
+ * the {@link org.eclipse.microprofile.lra.participant.InvalidLRAParticipantDefinitionException} 
+ * will be thrown during the application startup.
+ *
  * 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 returning {@link ParticipantStatus} 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

@@ -0,0 +1,54 @@
+/*
+ *******************************************************************************
+ * Copyright (c) 2019 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *******************************************************************************/
+package org.eclipse.microprofile.lra.participant;
+
+/**
+ * Runtime exception thrown when invalid non-JAX-RS LRA signature definition is detected.
+ * 
+ * The prohibited valid signatures are:
+ * Return type: 
+ *  - void: successfull execution is mapped to `Compensated` or `Completed` participant statuses, 
+ *     error execution is handled by exceptions thrown in the participant method
+ *      -  not applicable for `@Status` participant methods
+ *  - {@link org.eclipse.microprofile.lra.annotation.ParticipantStatus}
+ *  - {@link javax.ws.rs.core.Response}: handled similarly as for JAX-RS participant methods
+ *  - java.util.concurrent.CompletionStage: with the parameter of any of the previously 
+ *    defined types
+ * 
+ * Arguments: up to 2 arguments of types in this order:
+ *  - {@link java.net.URI}: representing current LRA context identification
+ *  - {@link java.net.URI}: representing potentional parent LRA context identification
+ *  
+ * Any other signature will result in deployment / start time of this type.
+ */
+public class InvalidLRAParticipantDefinitionException extends RuntimeException {
+
+    public InvalidLRAParticipantDefinitionException(String message) {
+        super(message);
+    }
+
+    public InvalidLRAParticipantDefinitionException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public InvalidLRAParticipantDefinitionException(Throwable cause) {
+        super(cause);
+    }
+}