Package org.eclipse.microprofile.lra.annotation.ws.rs

Enum LRA.Type

java.lang.Object

java.lang.Enum<LRA.Type>

org.eclipse.microprofile.lra.annotation.ws.rs.LRA.Type

All Implemented Interfaces:

Serializable, Comparable<LRA.Type>

Enclosing class:

LRA

public static enum LRA.Type
extends Enum<LRA.Type>

Enum Constant Summary

Enum Constants

Enum Constant	Description
MANDATORY	If called outside an LRA context the method is not executed and a 412 Precondition Failed HTTP status code is returned to the caller.
NESTED	An LRA (called the child) can be scoped within an existing LRA (called the parent) using the NESTED element value.
NEVER	If called outside an LRA context, i.e., LRA.LRA_HTTP_CONTEXT_HEADER is not present, the resource method execution must then continue outside an LRA context.
NOT_SUPPORTED	The resource method is executed without an LRA context.
REQUIRED	If called outside an LRA context the invoked method will run with a new context.
REQUIRES_NEW	If called outside an LRA context the invoked method will run with a new context.
SUPPORTS	If called outside an LRA context the resource method execution must then continue outside an LRA context.

Method Summary

Modifier and Type	Method	Description
static LRA.Type	valueOf(String name)	Returns the enum constant of this type with the specified name.
static LRA.Type[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

REQUIRED

public static final LRA.Type REQUIRED

If called outside an LRA context the invoked method will run with a new context.

If called inside an LRA context the invoked method will run with the same context.

REQUIRES_NEW

public static final LRA.Type REQUIRES_NEW

If called outside an LRA context the invoked method will run with a new context.

If called inside an LRA context the invoked method will run with a new context. The original context is ignored.

MANDATORY

public static final LRA.Type MANDATORY

If called outside an LRA context the method is not executed and a 412 Precondition Failed HTTP status code is returned to the caller.

If called inside a transaction context the resource method execution will then continue within that context.

SUPPORTS

public static final LRA.Type SUPPORTS

If called outside an LRA context the resource method execution must then continue outside an LRA context.

If called inside an LRA context the resource method execution must then continue with the same LRA context.

NOT_SUPPORTED

public static final LRA.Type NOT_SUPPORTED

The resource method is executed without an LRA context.

NEVER

public static final LRA.Type NEVER

If called outside an LRA context, i.e., LRA.LRA_HTTP_CONTEXT_HEADER is not present, the resource method execution must then continue outside an LRA context.

If called inside an LRA context, i.e., LRA.LRA_HTTP_CONTEXT_HEADER is present referring to an active, inactive or non-existent LRA, the method is not executed and a 412 Precondition Failed HTTP status code is returned to the caller.

NESTED

public static final LRA.Type NESTED

An LRA (called the child) can be scoped within an existing LRA (called the parent) using the NESTED element value. A new LRA will be created even if there is already one present when the method is invoked, i.e., these LRAs will then either be top-level or nested automatically depending upon the context within which they are created. If invoked without a context, the new LRA will be top level. If invoked with an LRA present, a new nested LRA is started whose outcome depends upon whether or not the enclosing LRA is closed or cancelled. The id of the parent LRA MUST be present in the header with the name "Long-Running-Action-Parent" and the value is of type URI.

A nested LRA is treated just like any other LRA with respect to participant enlistment. When an invocation results in the creation of a nested LRA that LRA becomes the "current context" and any further operations performed by the method will be executed with that context. The semantics of nested LRAs follows previous transactions models:

1. A nested LRA can close or cancel independently of its parent.
2. A nested LRA which has closed must retain the ability to cancel the effects if the the parent cancels. This requirement must be enforced by participants.
3. If a nested LRA cancels then all of its children must effectively cancel (even if they have previously been asked to close - see 2)
4. If a nested LRA closes then it, and all of its children, must close (but retain the ability to later cancel - see 2).

Downstream LRAs will only be part of this nesting hierarchy if the downstream methods carry the NESTED element, otherwise they are independent of the current nested LRA.

The reason why the model does not allow a cancelled nested LRA to be closed is because the business activity has already been compensated for which means there is no longer any outstanding work in need of completion.

On the other hand it does make sense to cancel the effects of a closed nested LRA since the work has been done and there is something that can be compensated for. In this case the LRA method invocation is allowed to proceed only if the participant is already enlisted with the LRA, otherwise the method invocation is rejected using a 412 Precondition Failed HTTP status code. If the method invocation causes the LRA to close then the Complete annotated method, if present, is not called again. If the LRA method causes the LRA to cancel then the nested LRA is moved to the LRAStatus.Cancelling state and the Compensate callback will be invoked.

Therefore, as a consequence of requirement 2, any activities performed in the context of a closed nested LRA must remain compensatable until the top level parent LRA finishes. So if the nested LRA is closed the participants registered with it will be asked to complete, but if the top level parent LRA is then told to cancel the nested participants will be told to compensate. This implies that the nested participants must be aware that they are nested and the JAX-RS header with the name "Long-Running-Action-Parent" is guaranteed to hold the parent context whenever a nested LRA is being propagated.

A participant which has completed can determine when the top level parent has closed by providing a Forget callback handler. When this method is called there is no longer a requirement to maintain the ability to reverse the effects of a closed nested LRA. This can be used by the participant to clean up any resources it used to implement this guarantee.

Note that it is possible for the same resource to be registered with both the parent and the child LRAs and in this case it will be asked to complete or compensate twice, once with the nested context and a second time with the parent context. The order in which the two callbacks are invoked is undefined.

Note that the elements of the LRA annotation always apply to the LRA context used to execute the annotated method. Thus elements such as LRA.timeLimit(), LRA.timeUnit(), LRA.cancelOn(), LRA.cancelOnFamily() and LRA.end() will always be applied to the nested or top level LRA.

Method Details

values

public static LRA.Type[] values()

Returns an array containing the constants of this enum type, in the order they are declared.

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static LRA.Type valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null