javax.faces.event.ListenerFor Maven / Gradle / Ivy
Show all versions of jboss-jsf-api_2.3_spec Show documentation
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.faces.event;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Inherited;
/**
* Classes tagged with this annotation are
* installed as listeners using the method {@link
* javax.faces.application.Application#subscribeToEvent} or {@link
* javax.faces.component.UIComponent#subscribeToEvent} (depending on the
* circumstances, described below).
*
*
*
* The default implementation must support attaching this annotation
* to {@link javax.faces.component.UIComponent} or {@link
* javax.faces.render.Renderer} classes. In both cases, the annotation
* processing described herein must commence during the implementation
* of any variant of {@link
* javax.faces.application.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 {@link ComponentSystemEventListener} and is a
UIComponent instance, "target" is the
UIComponent instance.
If the class to which this annotation is attached
implements {@link 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 {@link 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 {@link javax.faces.application.Application}
instance.
-
Determine the variant of subscribeToEvent()to
call and the parameters to pass to it.
If "target" is a UIComponent call {@link
javax.faces.component.UIComponent#subscribeToEvent(Class,
ComponentSystemEventListener)}, passing the {@link
#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 {@link
javax.faces.application.Application} instance, inspect the
value of the {@link #sourceClass} annotation attribute value.
If the value is Void.class, call {@link
javax.faces.application.Application#subscribeToEvent(Class,
SystemEventListener)}, passing the value of {@link
#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 {@link
javax.faces.application.Application#subscribeToEvent(Class,
Class, SystemEventListener)}, passing the value of {@link
#systemEventClass} as the first argument, the value of {@link
#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
* {@link PostAddToViewEvent} to all components that list it as their
* renderer.
*
*
* @since 2.0
*/
@Retention(value=RetentionPolicy.RUNTIME)
@Target(value=ElementType.TYPE)
@Inherited
@Repeatable(ListenersFor.class)
public @interface ListenerFor {
/**
* 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.
*
* @return the event class
*/
public Class systemEventClass();
/**
* The kind of object that emits events
* of the type given by the value of the {@link #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.
*
* @return the source class
*/
public Class sourceClass() default Void.class;
}