public static enum LRA.Type extends Enum<LRA.Type>
Enum Constant and 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.
|
Modifier and Type | Method and 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.
|
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.
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.
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.
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.
public static final LRA.Type NOT_SUPPORTED
The resource method is executed without an LRA context.
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.
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:
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.
public static LRA.Type[] values()
for (LRA.Type c : LRA.Type.values()) System.out.println(c);
public static LRA.Type valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullCopyright © 2018 – 2021 Eclipse Foundation. All rights reserved.
Use is subject to license terms.