|
19 | 19 | *******************************************************************************/ |
20 | 20 | package org.eclipse.microprofile.lra.annotation; |
21 | 21 |
|
22 | | -import org.eclipse.microprofile.lra.annotation.ws.rs.LRA; |
23 | | - |
24 | 22 | import java.lang.annotation.ElementType; |
25 | 23 | import java.lang.annotation.Retention; |
26 | 24 | import java.lang.annotation.RetentionPolicy; |
27 | 25 | import java.lang.annotation.Target; |
28 | 26 |
|
| 27 | +import org.eclipse.microprofile.lra.annotation.ws.rs.LRA; |
| 28 | + |
29 | 29 | /** |
30 | 30 | * <p> |
31 | | - * If a JAX-RS resource method is annotated with |
32 | | - * {@link LRA} and is invoked in the context of an LRA then |
33 | | - * the resource can ask to be notified when the LRA finishes |
34 | | - * by marking one of the other methods in the class with |
35 | | - * the <code>@AfterLRA</code> annotation. |
| 31 | + * If a JAX-RS resource method is annotated with {@link LRA} and is invoked in the context of an LRA then the resource |
| 32 | + * can ask to be notified when the LRA finishes by marking one of the other methods in the class with the |
| 33 | + * <code>@AfterLRA</code> annotation. |
36 | 34 | * </p> |
37 | 35 | * |
38 | 36 | * <p> |
39 | | - * The listener can register interest in the final outcome of an LRA at |
40 | | - * any time up until the LRA has reached a final state. In other words, |
41 | | - * if an LRA is closing or cancelling then listener registrations |
42 | | - * should be allowed. This is in contrast to registering for participant |
43 | | - * callbacks which are only allowed if the LRA is active. |
44 | | - * A consequence of this statement is that if a class is annotated with |
45 | | - * both the <code>AfterLRA</code> and the {@link Compensate} annotations and the LRA has |
46 | | - * already started closing or cancelling then the {@link LRA} method invocation |
47 | | - * will fail with a <code>412 Precondition Failed</code> JAX-RS response |
48 | | - * code because the {@link Compensate} method requires LRA to be Active. Without |
49 | | - * the {@link Compensate} method present, the after LRA listener would be registered successfully. |
| 37 | + * The listener can register interest in the final outcome of an LRA at any time up until the LRA has reached a final |
| 38 | + * state. In other words, if an LRA is closing or cancelling then listener registrations should be allowed. This is in |
| 39 | + * contrast to registering for participant callbacks which are only allowed if the LRA is active. A consequence of this |
| 40 | + * statement is that if a class is annotated with both the <code>AfterLRA</code> and the {@link Compensate} annotations |
| 41 | + * and the LRA has already started closing or cancelling then the {@link LRA} method invocation will fail with a |
| 42 | + * <code>412 Precondition Failed</code> JAX-RS response code because the {@link Compensate} method requires LRA to be |
| 43 | + * Active. Without the {@link Compensate} method present, the after LRA listener would be registered successfully. |
50 | 44 | * </p> |
51 | 45 | * |
52 | 46 | * <p> |
53 | | - * If the <code>AfterLRA</code> method is also a JAX-RS resource method |
54 | | - * then it MUST use the {@link javax.ws.rs.PUT} request method. In this |
55 | | - * case, the LRA context is made available to the annotated method |
56 | | - * via an HTTP header with the name |
57 | | - * {@link LRA#LRA_HTTP_ENDED_CONTEXT_HEADER} and the |
58 | | - * final status is passed to the method as plain text |
59 | | - * corresponding to one of the {@link LRAStatus} enum values. |
60 | | - * If this LRA was nested then the parent LRA MUST be present in the header |
61 | | - * {@link org.eclipse.microprofile.lra.annotation.ws.rs.LRA#LRA_HTTP_PARENT_CONTEXT_HEADER} |
62 | | - * and value is of type {@link java.net.URI}. For example: |
| 47 | + * If the <code>AfterLRA</code> method is also a JAX-RS resource method then it MUST use the {@link javax.ws.rs.PUT} |
| 48 | + * request method. In this case, the LRA context is made available to the annotated method via an HTTP header with the |
| 49 | + * name {@link LRA#LRA_HTTP_ENDED_CONTEXT_HEADER} and the final status is passed to the method as plain text |
| 50 | + * corresponding to one of the {@link LRAStatus} enum values. If this LRA was nested then the parent LRA MUST be present |
| 51 | + * in the header {@link org.eclipse.microprofile.lra.annotation.ws.rs.LRA#LRA_HTTP_PARENT_CONTEXT_HEADER} and value is |
| 52 | + * of type {@link java.net.URI}. For example: |
63 | 53 | * </p> |
64 | 54 | * |
65 | 55 | * <pre> |
|
73 | 63 | * </pre> |
74 | 64 | * |
75 | 65 | * <p> |
76 | | - * The implementation SHOULD keep resending the notification |
77 | | - * until it receives a <code>200 OK</code> status code from the |
78 | | - * resource method (which means that the method SHOULD be |
79 | | - * idempotent). |
80 | | - * If it stops retrying a warning message SHOULD be logged. |
| 66 | + * The implementation SHOULD keep resending the notification until it receives a <code>200 OK</code> status code from |
| 67 | + * the resource method (which means that the method SHOULD be idempotent). If it stops retrying a warning message SHOULD |
| 68 | + * be logged. |
81 | 69 | * </p> |
82 | 70 | * |
83 | 71 | * <p> |
84 | | - * If the <code>AfterLRA</code> method is not a JAX-RS resource method |
85 | | - * then the id of the LRA and its final status can be obtained |
86 | | - * by ensuring that the annotated method conforms to the |
87 | | - * signature: |
| 72 | + * If the <code>AfterLRA</code> method is not a JAX-RS resource method then the id of the LRA and its final status can |
| 73 | + * be obtained by ensuring that the annotated method conforms to the signature: |
88 | 74 | * </p> |
89 | 75 | * |
90 | 76 | * <pre> |
|
94 | 80 | * </pre> |
95 | 81 | * |
96 | 82 | * <p> |
97 | | - * The return type is ignored and the method name is not |
98 | | - * significant. |
| 83 | + * The return type is ignored and the method name is not significant. |
99 | 84 | * </p> |
100 | 85 | */ |
101 | 86 | @Retention(RetentionPolicy.RUNTIME) |
|
0 commit comments