diff --git a/api/src/main/java/org/eclipse/microprofile/lra/participant/JoinLRAException.java b/api/src/main/java/org/eclipse/microprofile/lra/participant/JoinLRAException.java deleted file mode 100644 index a59161d4..00000000 --- a/api/src/main/java/org/eclipse/microprofile/lra/participant/JoinLRAException.java +++ /dev/null @@ -1,52 +0,0 @@ -/* - ******************************************************************************* - * Copyright (c) 2018 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; - -import java.net.URI; - -/** - * An exception used to report failures during enlistment of a participant in an LRA - */ -public class JoinLRAException extends Exception { - private URI lraId; - private int statusCode; - - /** - * @return the specific reason for why the enlistment failed - */ - public int getStatusCode() { - return statusCode; - } - - /** - * @return the LRA that join request related to - */ - public URI getLraId() { - return lraId; - } - - public JoinLRAException(URI lraId, int statusCode, String message, Throwable cause) { - super(String.format("%s: %s", lraId, message), cause); - - this.lraId = lraId; - this.statusCode = statusCode; - } -} diff --git a/api/src/main/java/org/eclipse/microprofile/lra/participant/LRAManagement.java b/api/src/main/java/org/eclipse/microprofile/lra/participant/LRAManagement.java deleted file mode 100644 index f7b03b86..00000000 --- a/api/src/main/java/org/eclipse/microprofile/lra/participant/LRAManagement.java +++ /dev/null @@ -1,68 +0,0 @@ -/* - ******************************************************************************* - * Copyright (c) 2018 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; - -import javax.enterprise.context.ApplicationScoped; -import java.net.URI; -import java.time.temporal.ChronoUnit; - -@ApplicationScoped -public interface LRAManagement { - /** - * Join an existing LRA. - * - * @param participant an instance of a {@link LRAParticipant} that will be - * notified when the target LRA ends - * @param lraId the LRA that the join request pertains to - * @param timeLimit the time for which the participant should remain valid. When - * this time limit is exceeded the participant may longer be able - * to fulfil the protocol guarantees. - * @param unit the unit that the timeLimit parameter is expressed in - * - * @return a recovery URI for this enlistment - * - * @throws JoinLRAException if the request to the coordinator failed. - * {@link JoinLRAException#getCause()} and/or - * {@link JoinLRAException#getStatusCode()} may provide a more specific reason - */ - URI joinLRA(LRAParticipant participant, URI lraId, Long timeLimit, - ChronoUnit unit) - throws JoinLRAException; - - /** - * Join an existing LRA. In contrast to the other form of registration this - * method does not indicate a time limit for the participant meaning that the - * participant registration will remain valid until it terminates successfully - * or unsuccessfully (ie it will never be timed out externally). - * - * @param participant an instance of a {@link LRAParticipant} that will be - * notified when the target LRA ends - * @param lraId the LRA that the join request pertains to - * - * @return a recovery URI for this enlistment - * - * @throws JoinLRAException if the request to the coordinator failed. - * {@link JoinLRAException#getCause()} and/or - * {@link JoinLRAException#getStatusCode()} may provide a more specific reason - */ - URI joinLRA(LRAParticipant participant, URI lraId) throws JoinLRAException; - -} diff --git a/api/src/main/java/org/eclipse/microprofile/lra/participant/LRAParticipant.java b/api/src/main/java/org/eclipse/microprofile/lra/participant/LRAParticipant.java deleted file mode 100644 index 7de2c8ee..00000000 --- a/api/src/main/java/org/eclipse/microprofile/lra/participant/LRAParticipant.java +++ /dev/null @@ -1,66 +0,0 @@ -/* - ******************************************************************************* - * Copyright (c) 2018 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; - -import javax.ws.rs.NotFoundException; -import java.io.Serializable; -import java.net.URI; -import java.util.concurrent.Future; - -/** - * The API for notifying participants that a LRA is completing or cancelling. - * A participant joins with an LRA via a call to - * {@link LRAManagement#joinLRA(LRAParticipant, URI)} - */ -public interface LRAParticipant extends Serializable { - /** - * Notifies the participant that the LRA is closing - * @param lraId the LRA that is closing - * @return null if the participant completed successfully. If the participant - * cannot complete immediately it should return a future that the caller - * can used to monitor progress. If the JVM crashes before the participant - * can finish it should expect this method to be called again. If the - * participant fails to complete it must cancel the future or throw a - * TerminationException. - * @throws NotFoundException the participant does not know about this LRA - * @throws TerminationException the participant was unable to complete and will - * never be able to do so - */ - Future completeWork(URI lraId) - throws NotFoundException, TerminationException; - - /** - * Notifies the participant that the LRA is cancelling - * @param lraId the LRA that is closing - * @return null if the participant completed successfully. If the participant - * cannot complete immediately it should return a future that the - * caller can use to monitor progress. If the JVM crashes before - * the participant can finish it should expect this method to be - * called again. If the participant fails to complete it must cancel - * the future or throw a TerminationException. - * @throws NotFoundException the participant does not know about this LRA - * @throws TerminationException the participant was unable to complete and - * will never be able to do so - */ - Future compensateWork(URI lraId) - throws NotFoundException, TerminationException; -} - diff --git a/api/src/main/java/org/eclipse/microprofile/lra/participant/TerminationException.java b/api/src/main/java/org/eclipse/microprofile/lra/participant/TerminationException.java deleted file mode 100644 index 98654e75..00000000 --- a/api/src/main/java/org/eclipse/microprofile/lra/participant/TerminationException.java +++ /dev/null @@ -1,25 +0,0 @@ -/* - ******************************************************************************* - * Copyright (c) 2018 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; - -public class TerminationException extends Exception { - private static final long serialVersionUID = 1L; -} diff --git a/spec/src/main/asciidoc/microprofile-lra-spec.adoc b/spec/src/main/asciidoc/microprofile-lra-spec.adoc index 0a9d1e8e..491a001f 100644 --- a/spec/src/main/asciidoc/microprofile-lra-spec.adoc +++ b/spec/src/main/asciidoc/microprofile-lra-spec.adoc @@ -236,14 +236,8 @@ when the right subset of work (LRAs) is arrived at by the application will that subset be confirmed; all other LRAs will be told to cancel (complete in a failure state). -In the rest of this proposal we specify two different APIs for -controlling the life cycle of and participation in LRAs and a third API -for writing participants: - -1. <> for controlling -the life cycle and membership of LRAs -2. <> -to support services that do not use JAX-RS +In the rest of this proposal we specify an API for +controlling the life cycle of and participation in LRAs: [[java-annotations-for-lras]] === Java Annotations for LRAs @@ -966,87 +960,6 @@ survive system failures. The specification is not prescriptive about how an implementation achieves resiliency provided that it obeys the requirements of the specification as laid out in this document. -[[java-based-lra-participant-registration-api]] -=== Java based LRA participant registration API - -If an application does not directly expose JAX-RS endpoints for -compensation activities then participants can join an LRA directly using an instance of -<> -(https://github.com/eclipse/microprofile-lra/tree/master/api/src/main/java/org/eclipse/microprofile/lra/participant[github link]). -This interface requires that a participant be a Java class conforming to the -<> -(https://github.com/eclipse/microprofile-lra/tree/master/api/src/main/java/org/eclipse/microprofile/lra/participant[github link]). - -When an LRA is closed or cancelled the implementation [of this specification] is responsible -for invoking LRAParticipant completion or compensation -callbacks on any participants that were registered via the `LRAManagement#joinLRA` method. - -How the application obtains an LRAManagement instance is unspecified -(but CDI injection could be an obvious choice). For example, the following code listing -shows how to inject instances of the API and how to perform work in the context of an LRA: - -[source,java] ----- -@Path("/") -public class UnannotatedParticpant implements LRAParticipant { - @Inject - private LRAManagement lraManagement; - - public void doInTransaction() throws JoinLRAException - { - // start a new LRA with an unlimited timeout - // by invoking a suitable JAX-RS resource method annotated - // with @LRA(value = LRA.Type.REQUIRES_NEW, end = false) - ... - - // Join the LRA as a participant. - lraManagement.joinLRA(this, lraId, 0L, ChronoUnit.SECONDS); - - // do something interesting - - // close the LRA by invoking a suitable JAX-RS resource method - // annotated with, for example, - // @LRA(value = LRA.Type.SUPPORTS, end = true) - // This will cause the completion call back to be invoked - ... - - // the completeWork method will have been invoked at this point - } - - // the callback that will be invoked if the LRA is closed - @Override - public Future completeWork(URI lraId) - throws NotFoundException, TerminationException - { - return null; - } - - // the callback that will be invoked if the LRA is cancelled - @Override - public Future compensateWork(URI lraId) - throws NotFoundException, TerminationException - { - return null; - } -} ----- - -The framework must guarantee that participants will still be triggered (the LRA protocol still provides the "all or -nothing" guarantees that traditional transactions give). -This means that an implementation for all JAX-RS resources which implement the _LRAParticipant_ interface directly -or indirectly, MUST create some proxy which can be called by the spec implementation. + -This is to ensure that after this class has joined an LRA (through the _lraManagement.joinLRA()_ ) the _complete_ or -_compensate_ methods can be called by the spec implementation in case the microservice crashed before this notification could -be delivered. - -Serializable participants need to know how to contact the original -business application in order to trigger compensation activities whereas -a JAX-RS based solution need only persist resource paths which are likely -to correspond to existing microservice endpoints. In other words, from -an administrative and manageability point of view, it may be simpler to -use one of the other APIs such as the <>. - [[appendix-1]] == Appendix 1: Selected Javadoc API Descriptions @@ -1084,17 +997,3 @@ include::{sourcedir}/org/eclipse/microprofile/lra/annotation/Complete.java[Leave include::{sourcedir}/org/eclipse/microprofile/lra/annotation/ParticipantStatus.java/[ParticipantStatus] ---- <<< - -=== LRAManagement -[[source-LRAManagement]] ----- -include::{sourcedir}/org/eclipse/microprofile/lra/participant/LRAManagement.java[LRAManagement] ----- -<<< - -=== LRAParticipant -[[source-LRAParticipant]] ----- -include::{sourcedir}/org/eclipse/microprofile/lra/participant/LRAParticipant.java[LRAParticipant] ----- -<<<