| 1 |
/* |
| 2 |
* Copyright (c) 2021 Red Hat and others |
| 3 |
* |
| 4 |
* This program and the accompanying materials are made available under the |
| 5 |
* Apache Software License 2.0 which is available at: |
| 6 |
* https://www.apache.org/licenses/LICENSE-2.0. |
| 7 |
* |
| 8 |
* SPDX-License-Identifier: Apache-2.0 |
| 9 |
*/ |
| 10 |
|
| 11 |
package jakarta.enterprise.inject.build.compatible.spi; |
| 12 |
|
| 13 |
import jakarta.enterprise.lang.model.AnnotationInfo; |
| 14 |
import jakarta.enterprise.lang.model.declarations.ClassInfo; |
| 15 |
import jakarta.enterprise.lang.model.declarations.MethodInfo; |
| 16 |
import jakarta.enterprise.lang.model.declarations.ParameterInfo; |
| 17 |
import jakarta.enterprise.lang.model.types.Type; |
| 18 |
import java.util.Collection; |
| 19 |
import jakarta.enterprise.event.Reception; |
| 20 |
import jakarta.enterprise.event.TransactionPhase; |
| 21 |
|
| 22 |
/** |
| 23 |
* Observers are: |
| 24 |
* |
| 25 |
* <ul> |
| 26 |
* <li>observer methods</li> |
| 27 |
* <li>synthetic observers</li> |
| 28 |
* </ul> |
| 29 |
* |
| 30 |
* Observer methods directly correspond to a method declaration in program source code. |
| 31 |
* Synthetic observers don't and are instead defined through other mechanisms, such as |
| 32 |
* {@linkplain BuildCompatibleExtension extensions}. |
| 33 |
* |
| 34 |
* @since 4.0 |
| 35 |
*/ |
| 36 |
public interface ObserverInfo { |
| 37 |
/** |
| 38 |
* Returns the observed event type of this observer. |
| 39 |
* |
| 40 |
* @return the observed event type of this observer, never {@code null} |
| 41 |
*/ |
| 42 |
Type eventType(); |
| 43 |
|
| 44 |
/** |
| 45 |
* Returns a collection of observed event qualifiers, represented as {@link AnnotationInfo}. |
| 46 |
* |
| 47 |
* @return immutable collection of observed event qualifiers, never {@code null} |
| 48 |
*/ |
| 49 |
Collection<AnnotationInfo> qualifiers(); |
| 50 |
|
| 51 |
/** |
| 52 |
* Returns the {@linkplain ClassInfo class} that declares this observer. |
| 53 |
* In case of synthetic observers, returns the class that was designated |
| 54 |
* as a declaring class during synthetic observer registration. |
| 55 |
* |
| 56 |
* @return the class that declares this observer, never {@code null} |
| 57 |
*/ |
| 58 |
ClassInfo declaringClass(); |
| 59 |
|
| 60 |
/** |
| 61 |
* Returns the {@linkplain MethodInfo declaration} of this observer method. |
| 62 |
* Returns {@code null} if this is a synthetic observer. |
| 63 |
* |
| 64 |
* @return this observer method, or {@code null} if this is a synthetic observer |
| 65 |
*/ |
| 66 |
MethodInfo observerMethod(); |
| 67 |
|
| 68 |
/** |
| 69 |
* Returns the {@linkplain ParameterInfo event parameter} of this observer method. |
| 70 |
* Returns {@code null} if this is a synthetic observer. |
| 71 |
* |
| 72 |
* @return the event parameter of this observer method, or {@code null} if this is a synthetic observer |
| 73 |
*/ |
| 74 |
ParameterInfo eventParameter(); |
| 75 |
|
| 76 |
/** |
| 77 |
* Returns the {@link BeanInfo bean} that declares this observer method. |
| 78 |
* Returns {@code null} if this is a synthetic observer. |
| 79 |
* |
| 80 |
* @return the bean declaring this observer method, or {@code null} if this is a synthetic observer |
| 81 |
*/ |
| 82 |
BeanInfo bean(); |
| 83 |
|
| 84 |
/** |
| 85 |
* Returns whether this observer is synthetic. |
| 86 |
* |
| 87 |
* @return whether this observer is synthetic |
| 88 |
*/ |
| 89 |
boolean isSynthetic(); |
| 90 |
|
| 91 |
/** |
| 92 |
* Returns the priority of this observer. This is typically defined by adding |
| 93 |
* the {@link jakarta.annotation.Priority @Priority} annotation to the event parameter of the observer method. |
| 94 |
* If the annotation is not used, the default priority, as defined by the CDI specification, is returned, |
| 95 |
* |
| 96 |
* @return the priority of this observer |
| 97 |
*/ |
| 98 |
int priority(); |
| 99 |
|
| 100 |
/** |
| 101 |
* Returns whether this observer is asynchronous. For observer methods, this means whether |
| 102 |
* this observer method uses {@link jakarta.enterprise.event.ObservesAsync @ObservesAsync}. |
| 103 |
* |
| 104 |
* @return whether this observer is asynchronous |
| 105 |
*/ |
| 106 |
boolean isAsync(); |
| 107 |
|
| 108 |
/** |
| 109 |
* Returns the {@linkplain Reception reception type} of this observer. Allows distinguishing |
| 110 |
* conditional observer methods from always notified observer methods. |
| 111 |
* Returns {@link Reception#ALWAYS} if this is a synthetic observer. |
| 112 |
* |
| 113 |
* @return the reception type of this observer, never {@code null} |
| 114 |
*/ |
| 115 |
Reception reception(); |
| 116 |
|
| 117 |
/** |
| 118 |
* Returns the {@link TransactionPhase transaction phase} of this transactional observer. |
| 119 |
* Returns {@link TransactionPhase#IN_PROGRESS} if this is a regular synchronous observer. |
| 120 |
* Returns {@code null} if this is an asynchronous observer. |
| 121 |
* |
| 122 |
* @return the transaction phase of this observer, or {@code null} if this is an asynchronous observer |
| 123 |
*/ |
| 124 |
TransactionPhase transactionPhase(); |
| 125 |
} |