javax.faces.lifecycle.Lifecycle Maven / Gradle / Ivy
Show all versions of jakarta.faces 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.lifecycle;
import javax.faces.FacesException;
import javax.faces.context.FacesContext;
import javax.faces.event.PhaseListener;
/**
* Lifecycle manages the
* processing of the entire lifecycle of a particular Jakarta Server Faces
* request. It is responsible for executing all of the phases that have
* been defined by the Jakarta Server Faces Specification, in the specified
* order, unless otherwise directed by activities that occurred during
* the execution of each phase.
*
* An instance of Lifecycle is created by calling the
* getLifecycle() method of {@link LifecycleFactory}, for
* a specified lifecycle identifier. Because this instance is
* shared across multiple simultaneous requests, it must be implemented
* in a thread-safe manner.
*/
public abstract class Lifecycle {
// ---------------------------------------------------------- Public Methods
/**
* Register a new {@link PhaseListener} instance that is interested in
* being notified before and after the processing for standard phases of
* the request processing lifecycle.
*
* @param listener The {@link PhaseListener} to be registered
*
* @throws NullPointerException if listener
* is null
*/
public abstract void addPhaseListener(PhaseListener listener);
/**
* Execute all of the phases of the request processing lifecycle,
* up to but not including the Render Response phase,
* as described in the Jakarta Server Faces Specification, in the specified
* order. The processing flow can be affected (by the application,
* by components, or by event listeners) by calls to the
* renderResponse() or responseComplete()
* methods of the {@link FacesContext} instance associated with
* the current request.
*
* @param context FacesContext for the request to be processed
*
* @throws FacesException if thrown during the execution of the
* request processing lifecycle
* @throws NullPointerException if context
* is null
*/
public abstract void execute(FacesContext context) throws FacesException;
/**
* Create or restore the {@link
* ClientWindow} to be used to display the {@link
* javax.faces.component.UIViewRoot} for this run through the
* lifecycle. See the class documentation for {@link ClientWindow}
* for an overview of the feature.
*
* If {@link javax.faces.context.ExternalContext#getClientWindow()} returns
* null, create a new instance of ClientWindow using the
* {@link ClientWindowFactory}. If the result is non-null, call
* {@link ClientWindow#decode(javax.faces.context.FacesContext)} on it.
* Store the new ClientWindow by calling
* {@link javax.faces.context.ExternalContext#setClientWindow(javax.faces.lifecycle.ClientWindow)}.
*
* @param context the {@link FacesContext} for this request.
*
* @since 2.2
*/
public void attachWindow(FacesContext context) {
}
/**
* Return the set of registered {@link PhaseListener}s for this
* {@link Lifecycle} instance. If there are no registered listeners,
* a zero-length array is returned.
*
* @return the set of registered {@link PhaseListener}s
*/
public abstract PhaseListener[] getPhaseListeners();
/**
* Deregister an existing {@link PhaseListener} instance that is no
* longer interested in being notified before and after the processing
* for standard phases of the request processing lifecycle. If no such
* listener instance has been registered, no action is taken.
*
* @param listener The {@link PhaseListener} to be deregistered
* @throws NullPointerException if listener
* is null
*/
public abstract void removePhaseListener(PhaseListener listener);
/**
* Execute the Render Response phase of the request
* processing lifecycle, unless the responseComplete()
* method has been called on the {@link FacesContext} instance
* associated with the current request.
*
* @param context FacesContext for the request being processed
*
* @throws FacesException if an exception is thrown during the execution
* of the request processing lifecycle
* @throws NullPointerException if context
* is null
*/
public abstract void render(FacesContext context) throws FacesException;
}