jakarta.faces.event.FacesEvent Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 1997, 2020 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 jakarta.faces.event;
import java.util.EventObject;
import jakarta.faces.component.UIComponent;
import jakarta.faces.component.UIViewAction;
import jakarta.faces.component.UIViewRoot;
import jakarta.faces.context.FacesContext;
/**
*
* FacesEvent is the base class for user interface and application events that can be fired by
* {@link UIComponent}s. Concrete event classes must subclass {@link FacesEvent} in order to be supported by the request
* processing lifecycle.
*
*/
public abstract class FacesEvent extends EventObject {
private static final long serialVersionUID = -367663885586773794L;
/**
*
* Stores the Faces context.
*
*/
private transient FacesContext facesContext;
/**
*
* Construct a new event object from the specified source component.
*
*
* @param component Source {@link UIComponent} for this event
* @throws IllegalArgumentException if component is null
*/
public FacesEvent(UIComponent component) {
super(component);
}
/**
*
* Construct a new event object from the Faces context and specified source component.
*
*
* @param facesContext the Faces context.
* @param component Source {@link UIComponent} for this event.
* @throws IllegalArgumentException if component is null
* @since 2.3
*/
public FacesEvent(FacesContext facesContext, UIComponent component) {
this(component);
this.facesContext = facesContext;
}
// -------------------------------------------------------------- Properties
/**
*
* Return the source {@link UIComponent} that sent this event.
*
* @return the source UI component.
*/
public UIComponent getComponent() {
return (UIComponent) getSource();
}
/**
*
* Get the Faces context.
*
*
*
* If the constructor was passed a FacesContext we return it, otherwise we call FacesContext.getCurrentInstance() and
* return it.
*
*
* @return the Faces context.
* @since 2.3
*/
public FacesContext getFacesContext() {
/*
* Note because UIViewAction is decorating the FacesContext during the execution of a request we cannot rely on the
* saved FacesContext as it would be the original FacesContext (which is what we should be able to rely on).
*
* TODO - remove UIViewAction dependency on decorating the FacesContext.
*/
if (!(source instanceof UIViewAction) && facesContext != null) {
return facesContext;
}
return FacesContext.getCurrentInstance();
}
private PhaseId phaseId = PhaseId.ANY_PHASE;
/**
*
* Return the identifier of the request processing phase during which this event should be delivered. Legal values are
* the singleton instances defined by the {@link PhaseId} class, including PhaseId.ANY_PHASE, which is the
* default value.
*
*
* @return the phase id.
*/
public PhaseId getPhaseId() {
return phaseId;
}
/**
*
* Set the {@link PhaseId} during which this event will be delivered.
*
*
* @param phaseId the phase id.
* @throws IllegalArgumentException phaseId is null.
*/
public void setPhaseId(PhaseId phaseId) {
if (null == phaseId) {
throw new IllegalArgumentException();
}
this.phaseId = phaseId;
}
// ------------------------------------------------- Event Broadcast Methods
/**
*
* Convenience method to queue this event for broadcast at the end of the current request processing lifecycle phase.
*
*
* @throws IllegalStateException if the source component for this event is not a descendant of a {@link UIViewRoot}
*/
public void queue() {
getComponent().queueEvent(this);
}
/**
*
* Return true if this {@link FacesListener} is an instance of a listener class that this event supports.
* Typically, this will be accomplished by an "instanceof" check on the listener class.
*
*
* @param listener {@link FacesListener} to evaluate
* @return true if it is the appropriate instance, false otherwise.
*/
public abstract boolean isAppropriateListener(FacesListener listener);
/**
*
* Broadcast this {@link FacesEvent} to the specified {@link FacesListener}, by whatever mechanism is appropriate.
* Typically, this will be accomplished by calling an event processing method, and passing this {@link FacesEvent} as a
* paramter.
*
*
* @param listener {@link FacesListener} to send this {@link FacesEvent} to
*
* @throws AbortProcessingException Signal the Jakarta Faces implementation that no further processing on the
* current event should be performed
*/
public abstract void processListener(FacesListener listener);
}