@Retention(value=RUNTIME) @Target(value=TYPE) @Inherited @Repeatable(value=ListenersFor.class) public @interface ListenerFor
Classes tagged with this annotation are installed as listeners using the method
Application.subscribeToEvent(java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Class<?>, jakarta.faces.event.SystemEventListener) or
UIComponent.subscribeToEvent(java.lang.Class<? extends jakarta.faces.event.SystemEvent>, jakarta.faces.event.ComponentSystemEventListener) (depending on the circumstances, described below).
The default implementation must support attaching this annotation to UIComponent or
Renderer classes. In both cases, the annotation processing described herein must
commence during the implementation of any variant of
Application.createComponent() and must complete before the
UIComponent instance is returned from createComponent(). The annotation processing must
proceed according to an algorithm semantically equivalent to the following.
If this annotation is not present on the class in question, no action must be taken.
Determine the "target" on which to call subscribeToEvent.
If the class to which this annotation is attached implements ComponentSystemEventListener and is a
UIComponent instance, "target" is the UIComponent instance.
If the class to which this annotation is attached implements ComponentSystemEventListener and is a
Renderer instance, "target" is the UIComponent instance that is to be rendered by this
Renderer instance.
If the class to which this annotation is attached implements ComponentSystemEventListener and is neither an
instance of Renderer nor UIComponent, the action taken is unspecified. This case must not
trigger any kind of error.
If the class to which this annotation is attached implements SystemEventListener and does not implement
ComponentSystemEventListener, "target" is the Application instance.
Determine the variant of subscribeToEvent()to call and the parameters to pass to it.
If "target" is a UIComponent call
UIComponent.subscribeToEvent(Class, ComponentSystemEventListener), passing the
systemEventClass() of the annotation as the first argument and the instance of the class to which this
annotation is attached (which must implement ComponentSystemEventListener) as the second argument.
If "target" is the Application instance, inspect the value of the
sourceClass() annotation attribute value.
If the value is Void.class, call
Application.subscribeToEvent(Class, SystemEventListener), passing the value of
systemEventClass() as the first argument and the instance of the class to which this annotation is attached
(which must implement SystemEventListener) as the second
argument.
Otherwise, call Application.subscribeToEvent(Class, Class, SystemEventListener),
passing the value of systemEventClass() as the first argument, the value of sourceClass() as the second
argument, and the instance of the class to which this annotation is attached (which must implement
SystemEventListener) as the third
argument.
Example: The standard renderer for jakarta.faces.resource.Stylesheet must have the following annotation
declaration:
@ListenerFor(systemEventClass=PostAddToViewEvent.class)
This will cause the renderer to be added as a listener for the PostAddToViewEvent to all components that list
it as their renderer.
| Modifier and Type | Required Element and Description |
|---|---|
java.lang.Class<? extends SystemEvent> |
systemEventClass
The kind of system event for which this class will be installed as a listener. |
| Modifier and Type | Optional Element and Description |
|---|---|
java.lang.Class |
sourceClass
The kind of object that emits events of the type given by the value of the |
public abstract java.lang.Class<? extends SystemEvent> systemEventClass
The kind of system event for which this class will be installed as a listener. The implementation only supports exact
matches on the Class and must not honor subclass relationships. It is valid to have EL Expressions in
the value of this attribute, as long as the expression resolves to an instance of the expected type.
public abstract java.lang.Class sourceClass
The kind of object that emits events of the type given by the value of the systemEventClass() attribute. It is
valid to have Jakarta Expression Language Expressions in the value of this attribute, as long as the expression
resolves to an instance of the expected type.