javax.faces.context.FacesContext Maven / Gradle / Ivy
Show all versions of jsf-api Show documentation
/*
* $Id: FacesContext.java,v 1.72.4.2 2008/06/11 18:03:04 rlubke Exp $
*/
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright 1997-2007 Sun Microsystems, Inc. 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.html
* or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt.
* Sun designates this particular file as subject to the "Classpath" exception
* as provided by Sun in the GPL Version 2 section of the License file that
* accompanied this code. If applicable, add the following below the License
* Header, with the fields enclosed by brackets [] replaced by your own
* identifying information: "Portions Copyrighted [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.context;
import java.util.Iterator;
import java.util.Map;
import javax.faces.application.Application;
import javax.faces.application.FacesMessage;
import javax.faces.application.FacesMessage.Severity;
import javax.faces.component.UIComponent;
import javax.faces.component.UIViewRoot;
import javax.faces.render.RenderKit;
import javax.el.ELContext;
/**
* FacesContext contains all of the per-request state
* information related to the processing of a single JavaServer Faces request,
* and the rendering of the corresponding response. It is passed to, and
* potentially modified by, each phase of the request processing lifecycle.
*
* A {@link FacesContext} instance is associated with a particular
* request at the beginning of request processing, by a call to the
* getFacesContext() method of the {@link FacesContextFactory}
* instance associated with the current web application. The instance
* remains active until its release() method is called, after
* which no further references to this instance are allowed. While a
* {@link FacesContext} instance is active, it must not be referenced
* from any thread other than the one upon which the servlet container
* executing this web application utilizes for the processing of this request.
*
*/
public abstract class FacesContext {
// -------------------------------------------------------------- Properties
/**
* Return the {@link Application} instance associated with this
* web application.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract Application getApplication();
/**
* Return an Iterator over the client identifiers for
* which at least one {@link javax.faces.application.FacesMessage} has been queued. If there are no
* such client identifiers, an empty Iterator is returned.
* If any messages have been queued that were not associated with any
* specific client identifier, a null value will be included
* in the iterated values. The elements in the Iterator must
* be returned in the order in which they were added with {@link #addMessage}.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract Iterator getClientIdsWithMessages();
/**
* Return the ELContext instance for this
* FacesContext instance. This ELContext
* instance has the same lifetime and scope as the
* FacesContext instance with which it is associated,
* and may be created lazily the first time this method is called
* for a given FacesContext instance. Upon creation of
* the ELContext instance, the implementation must take the
* following action:
*
*
*
* Call the {@link ELContext#putContext} method on the
* instance, passing in FacesContext.class and the
* this reference for the FacesContext
* instance itself.
If the Collection returned by {@link
* javax.faces.application.Application#getELContextListeners} is
* non-empty, create an instance of {@link
* javax.el.ELContextEvent} and pass it to each {@link
* javax.el.ELContextListener} instance in the
* Collection by calling the {@link
* javax.el.ELContextListener#contextCreated} method.
*
* The default implementation throws
* UnsupportedOperationException and is provided
* for the sole purpose of not breaking existing applications that extend
* this class.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*
* @since 1.2
*/
public ELContext getELContext() {
Map m = (Map) getExternalContext().getRequestMap().get("com.sun.faces.util.RequestStateManager");
if (m != null) {
FacesContext impl = (FacesContext) m.get("com.sun.faces.FacesContextImpl");
if (impl != null) {
return impl.getELContext();
} else {
throw new UnsupportedOperationException();
}
}
throw new UnsupportedOperationException();
}
/**
* Return the {@link ExternalContext} instance for this
* FacesContext instance.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract ExternalContext getExternalContext();
/**
* Return the maximum severity level recorded on any
* {@link javax.faces.application.FacesMessage}s that has been queued, whether or not they are
* associated with any specific {@link UIComponent}. If no such messages
* have been queued, return null.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract Severity getMaximumSeverity();
/**
* Return an Iterator over the {@link javax.faces.application.FacesMessage}s
* that have been queued, whether or not they are associated with any
* specific client identifier. If no such messages have been queued,
* return an empty Iterator. The elements of the Iterator
* must be returned in the order in which they were added with calls to {@link
* #addMessage}.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract Iterator getMessages();
/**
* Return an Iterator over the {@link javax.faces.application.FacesMessage}s that
* have been queued that are associated with the specified client identifier
* (if clientId is not null), or over the
* {@link javax.faces.application.FacesMessage}s that have been queued that are not associated with
* any specific client identifier (if clientId is
* null). If no such messages have been queued, return an
* empty Iterator. The elements of the Iterator
* must be returned in the order in which they were added with calls to {@link
* #addMessage}.
*
* @param clientId The client identifier for which messages are
* requested, or null for messages not associated with
* any client identifier
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract Iterator getMessages(String clientId);
/**
* Return the {@link RenderKit} instance for the render kit identifier
* specified on our {@link UIViewRoot}, if there is one. If there is no
* current {@link UIViewRoot}, if the {@link UIViewRoot} does not have a
* specified renderKitId, or if there is no {@link RenderKit}
* for the specified identifier, return null instead.
*/
public abstract RenderKit getRenderKit();
/**
* Return true if the renderResponse()
* method has been called for the current request.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract boolean getRenderResponse();
/**
* Return true if the responseComplete()
* method has been called for the current request.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract boolean getResponseComplete();
/**
* Return the {@link ResponseStream} to which components should
* direct their binary output. Within a given response, components
* can use either the ResponseStream or the ResponseWriter,
* but not both.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract ResponseStream getResponseStream();
/**
*
Set the {@link ResponseStream} to which components should
* direct their binary output.
*
* @param responseStream The new ResponseStream for this response
*
* @throws NullPointerException if responseStream
* is null
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract void setResponseStream(ResponseStream responseStream);
/**
*
Return the {@link ResponseWriter} to which components should
* direct their character-based output. Within a given response,
* components can use either the ResponseStream or the ResponseWriter,
* but not both.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract ResponseWriter getResponseWriter();
/**
*
Set the {@link ResponseWriter} to which components should
* direct their character-based output.
*
* @param responseWriter The new ResponseWriter for this response
*
* @throws IllegalStateException if this method is called after
* this instance has been released
* @throws NullPointerException if responseWriter
* is null
*/
public abstract void setResponseWriter(ResponseWriter responseWriter);
/**
*
Return the root component that is associated with the this request.
*
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract UIViewRoot getViewRoot();
/**
* Set the root component that is associated with this request.
* This method can only be called by the application handler (or a
* class that the handler calls), and only during the Invoke
* Application phase of the request processing lifecycle.
*
* @param root The new component {@link UIViewRoot} component
*
* @throws IllegalStateException if this method is called after
* this instance has been released
* @throws NullPointerException if root
* is null
*/
public abstract void setViewRoot(UIViewRoot root);
// ---------------------------------------------------------- Public Methods
/**
* Append a {@link javax.faces.application.FacesMessage} to the set of messages associated with
* the specified client identifier, if clientId is
* not null. If clientId is null,
* this {@link javax.faces.application.FacesMessage} is assumed to not be associated with any
* specific component instance.
*
* @param clientId The client identifier with which this message is
* associated (if any)
* @param message The message to be appended
*
* @throws IllegalStateException if this method is called after
* this instance has been released
* @throws NullPointerException if message
* is null
*/
public abstract void addMessage(String clientId, FacesMessage message);
/**
* Release any resources associated with this
* FacesContext instance. Faces implementations may
* choose to pool instances in the associated {@link
* FacesContextFactory} to avoid repeated object creation and
* garbage collection. After release() is called on a
* FacesContext instance (until the
* FacesContext instance has been recycled by the
* implementation for re-use), calling any other methods will cause
* an IllegalStateException to be thrown.
*
* The implementation must call {@link #setCurrentInstance}
* passing null to remove the association between this
* thread and this dead FacesContext instance.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract void release();
/**
* Signal the JavaServer faces implementation that, as soon as the
* current phase of the request processing lifecycle has been completed,
* control should be passed to the Render Response phase,
* bypassing any phases that have not been executed yet.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract void renderResponse();
/**
* Signal the JavaServer Faces implementation that the HTTP response
* for this request has already been generated (such as an HTTP redirect),
* and that the request processing lifecycle should be terminated as soon
* as the current phase is completed.
*
* @throws IllegalStateException if this method is called after
* this instance has been released
*/
public abstract void responseComplete();
// ---------------------------------------------------------- Static Methods
/**
* The ThreadLocal variable used to record the
* {@link FacesContext} instance for each processing thread.
*/
private static ThreadLocal instance = new ThreadLocal() {
protected FacesContext initialValue() { return (null); }
};
/**
* Return the {@link FacesContext} instance for the request that is
* being processed by the current thread, if any.
*/
public static FacesContext getCurrentInstance() {
return (instance.get());
}
/**
* Set the {@link FacesContext} instance for the request that is
* being processed by the current thread.
*
* @param context The {@link FacesContext} instance for the current
* thread, or null if this thread no longer has a
* FacesContext instance.
*
*/
protected static void setCurrentInstance(FacesContext context) {
if (context == null) {
instance.remove();
} else {
instance.set(context);
}
}
}