javax.faces.event

## Annotation Type ListenerFor

-     @Retention(value=RUNTIME)
      @Target(value=TYPE)
      @Inherited
      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.

Since:
  2.0

- - ### Required Element Summary

    Required Elements
    Modifier and Type | Required Element and Description
    --- | ---
    `Class<? extends SystemEvent>` | `systemEventClass` The kind of system event for which this class will be installed as a listener.

  - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `Class` | `sourceClass` The kind of object that emits events of the type given by the value of the `systemEventClass()` attribute.

- - ### Element Detail

    - #### systemEventClass

          public abstract 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.

    - #### sourceClass

          public abstract 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 EL Expressions in the value of this attribute, as long as the expression resolves to an instance of the expected type.

      Default:
        java.lang.Void.class

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.