All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.eclipse.microprofile.lra.annotation.Complete Maven / Gradle / Ivy

There is a newer version: 2.0
Show newest version
/*
 *******************************************************************************
 * Copyright (c) 2018-2021 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.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.eclipse.microprofile.lra.annotation.ws.rs.LRA;

/**
 * 

* If a resource method executes in the context of an LRA and if the containing class has a method annotated with * @Complete (as well as method annotated with @Compensate) then this Complete method * will be invoked if the LRA is closed. The resource should attempt to perform any clean up activities relating to any * actions it performed in the context of the LRA. If the annotation is present on more than one method then an * arbitrary one will be chosen. The LRA specification makes no guarantees about when the Complete method will be * invoked, just that it will eventually be called. *

* *

* In the case where the ability to complete the Long Running Action is time bounded, you can limit the lifespan of the * Long Running action by providing values for the {@link LRA#timeLimit()} and {@link LRA#timeUnit()} timeUnit} * attributes. When the time limit is reached the LRA becomes eligible for automatic cancellation. *

* *

* If the annotation is applied to a JAX-RS resource method then the request method MUST be {@link jakarta.ws.rs.PUT}. * 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 LRA#LRA_HTTP_PARENT_CONTEXT_HEADER} and the * header value will be of type {@link java.net.URI}. *

* *

* If the annotated method is not a JAX-RS resource method then the id of the currently running LRA and its parent LRA * (if it is nested) can be obtained by adhering to predefined method signatures as defined in the LRA specification * document. For example, *

* *
 *     
 *        @Complete
 *        public void complete(URI lraId, URI parentId) { ...}
 *     
 * 
* *

* would be a valid completion method declaration. If an invalid signature is detected the implementation of this * specification MUST prohibit successful startup of the application (e.g. with a runtime exception). *

* *

* If the participant cannot complete immediately then it must report that completion is in progress by either returning * a future (such as {@link java.util.concurrent.CompletionStage}) which will eventually report one of the final states, * or a 202 Accepted JAX-RS response code or, in the case of non JAX-RS resource methods, by returning * {@link ParticipantStatus#Completing} (see the specification document for more details). *

* *

* Note that according to the state model defined by {@link LRAStatus}, it is not possible to receive completion * notifications after an LRA has been asked to close. Therefore combining this annotation with an @LRA * annotation that does not start a new LRA will result in a 412 PreCondition Failed JAX-RS response code. * On the other hand, combining it with an @LRA annotation that begins a new LRA can in certain use * cases make sense, but in this case the LRA that this method is being asked to complete for will be unavailable. *

* *

* If the method is a JAX-RS resource method (or is a non JAX-RS method annotated with @Complete with * return type jakarta.ws.rs.core.Response) then the following are the only valid response codes: *

* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
JAX-RS Completion Response Codes 
CodeResponse BodyMeaning
200EmptyThe resource has successfully completed
202EmptyThe resource is still attempting completion
409{@link ParticipantStatus} enum value *

* The resource has failed to complete. The payload contains the reason for the failure. A participant MUST remember * this state until its {@link Forget} method is called. *

*

* The actual value is not important but it MUST correspond to a valid {@link ParticipantStatus} enum value. For * example, if completion was not possible because the resource already compensated (without being asked to) then a * value such as {@link ParticipantStatus#Compensated} would be appropriate or if it was due to a generic failure then * {@link ParticipantStatus#FailedToComplete} would be valid. If the response body does not contain a valid status then * the implementation MUST either reinvoke the method or discover the status using the {@link Status} annotation if * present. *

*

* Note that the actual state as reported by the {@link Status} method MUST be * {@link ParticipantStatus#FailedToComplete} *

*
410EmptyThe resource does not know about the LRA
* *

* The implementation will handle the return code 410 in the same way as the return code 200. Specifically, when the * implementation calls the Complete method as a result of the LRA being closed and the participant returns the code * 410, the implementation assumes that the action is completed and participant returns a 410 since participant is * allowed to forget about an action which is completely handled by the participant. *

* *

* If any other code is returned (or, in the 409 case, the body does not correspond to a valid state) then the * implementation SHOULD either keep retrying or attempt to discover the status by calling the {@link Status} method if * present or a combination of both. If the implementation stops retrying then it SHOULD log a warning. An example * scenario where the implementation might attempt to invoke the complete method twice and the status method is as * follows: *

* *
    *
  1. The implementation invokes the complete method via JAX-RS.
  2. *
  3. The JAX-RS server returns a 500 code (i.e., the notification does not reach the participant).
  4. *
  5. If there is a status method then the implementation uses that to get the current state of the participant. If the * status is Active then the implementation may infer that the original request never reached the participant so it is * safe to reinvoke the complete method.
  6. *
*/ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD}) public @interface Complete { }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy