@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.