@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 javax.faces.event.SystemEvent>, java.lang.Class<?>, javax.faces.event.SystemEventListener) or UIComponent.subscribeToEvent(java.lang.Class<? extends javax.faces.event.SystemEvent>, javax.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
javax.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.