javax.faces.event.ListenerFor Maven / Gradle / Ivy
Show all versions of jboss-jsf-api_2.0_spec
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2011 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.faces.event;
import java.lang.annotation.ElementType;
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
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.
*/
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 EL Expressions in the value of
* this attribute, as long as the expression resolves to an instance
* of the expected type.
*/
public Class sourceClass() default Void.class;
}