You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2007/10/27 18:20:19 UTC
svn commit: r589146 - in
/myfaces/core/trunk/api/src/main/java/javax/faces/application:
StateManager.java ViewHandler.java
Author: skitching
Date: Sat Oct 27 09:20:18 2007
New Revision: 589146
URL: http://svn.apache.org/viewvc?rev=589146&view=rev
Log:
Add documentation only
Modified:
myfaces/core/trunk/api/src/main/java/javax/faces/application/StateManager.java
myfaces/core/trunk/api/src/main/java/javax/faces/application/ViewHandler.java
Modified: myfaces/core/trunk/api/src/main/java/javax/faces/application/StateManager.java
URL: http://svn.apache.org/viewvc/myfaces/core/trunk/api/src/main/java/javax/faces/application/StateManager.java?rev=589146&r1=589145&r2=589146&view=diff
==============================================================================
--- myfaces/core/trunk/api/src/main/java/javax/faces/application/StateManager.java (original)
+++ myfaces/core/trunk/api/src/main/java/javax/faces/application/StateManager.java Sat Oct 27 09:20:18 2007
@@ -22,7 +22,34 @@
/**
- * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
+ * Responsible for storing sufficient information about a component tree so that an identical tree
+ * can later be recreated.
+ * <p>
+ * It is up to the concrete implementation to decide whether to use information from the "view template"
+ * that was used to first create the view, or whether to store sufficient information to enable the
+ * view to be restored without any reference to the original template. However as JSF components have
+ * mutable fields that can be set by code, and affected by user input, at least some state does need
+ * to be kept in order to recreate a previously-existing component tree.
+ * <p>
+ * There are two different options defined by the specification: "client" and "server" state.
+ * <p>
+ * When "client" state is configured, all state information required to create the tree is embedded within
+ * the data rendered to the client. Note that because data received from a remote client must always be
+ * treated as "tainted", care must be taken when using such data. Some StateManager implementations may
+ * use encryption to ensure that clients cannot modify the data, and that the data received on postback
+ * is therefore trustworthy.
+ * <p>
+ * When "server" state is configured, the data is saved somewhere "on the back end", and (at most) a
+ * token is embedded in the data rendered to the user.
+ * <p>
+ * This class is usually invoked by a concrete implementation of ViewHandler.
+ * <p>
+ * Note that class ViewHandler isolates JSF components from the details of the request format. This class
+ * isolates JSF components from the details of the response format. Because request and response are usually
+ * tightly coupled, the StateManager and ViewHandler implementations are also usually fairly tightly coupled
+ * (ie the ViewHandler/StateManager implementations come as pairs).
+ * <p>
+ * See Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
*
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
@@ -34,12 +61,36 @@
public static final String STATE_SAVING_METHOD_SERVER = "server";
private Boolean _savingStateInClient = null;
+ /**
+ * Invokes getTreeStructureToSave and getComponentStateToSave, then return an object that wraps the two
+ * resulting objects. This object can then be passed to method writeState.
+ */
public abstract StateManager.SerializedView saveSerializedView(javax.faces.context.FacesContext context);
+ /**
+ * Return data that is sufficient to recreate the component tree that is the viewroot of the specified
+ * context, but without restoring the state in the components.
+ * <p>
+ * Using this data, a tree of components which has the same "shape" as the original component
+ * tree can be recreated. However the component instances themselves will have only their default
+ * values, ie their member fields will not have been set to the original values.
+ */
protected abstract Object getTreeStructureToSave(javax.faces.context.FacesContext context);
+ /**
+ * Return data that can be applied to a component tree created using the "getTreeStructureToSave"
+ * method.
+ */
protected abstract Object getComponentStateToSave(javax.faces.context.FacesContext context);
+ /**
+ * Associate the provided state object with the current response being generated.
+ * <p>
+ * When client-side state is enabled, it is expected that method writes the data contained in the
+ * state parameter to the response somehow.
+ * <p>
+ * When server-side state is enabled, at most a "token" is expected to be written.
+ */
public abstract void writeState(javax.faces.context.FacesContext context,
StateManager.SerializedView state)
throws java.io.IOException;
Modified: myfaces/core/trunk/api/src/main/java/javax/faces/application/ViewHandler.java
URL: http://svn.apache.org/viewvc/myfaces/core/trunk/api/src/main/java/javax/faces/application/ViewHandler.java?rev=589146&r1=589145&r2=589146&view=diff
==============================================================================
--- myfaces/core/trunk/api/src/main/java/javax/faces/application/ViewHandler.java (original)
+++ myfaces/core/trunk/api/src/main/java/javax/faces/application/ViewHandler.java Sat Oct 27 09:20:18 2007
@@ -22,7 +22,41 @@
import java.util.Locale;
/**
- * see Javadoc of <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>
+ * A ViewHandler manages the component-tree-creation and component-tree-rendering parts
+ * of a request lifecycle (ie "create view", "restore view" and "render response").
+ * <p>
+ * A ViewHandler is responsible for generating the component tree when a new view is
+ * requested; see method "createView".
+ * <p>
+ * When the user performs a "postback", ie activates a UICommand component within a view,
+ * then the ViewHandler is resonsible for recreating a view tree identical to the one
+ * used previously to render that view; see method "restoreView".
+ * <p>
+ * And the ViewHandler is also responsible for rendering the final output to be sent to the
+ * user by invoking the rendering methods on components; see method "renderView".
+ * <p>
+ * This class also isolates callers from the underlying request/response system. In particular,
+ * this class does not explicitly depend upon the javax.servlet apis. This allows JSF to be
+ * used on servers that do not implement the servlet API (for example, plain CGI).
+ * <p>
+ * Examples:
+ * <ul>
+ * <li>A JSP ViewHandler exists for using "jsp" pages as the presentation technology.
+ * This class then works together with a taghandler class and a jsp servlet class to
+ * implement the methods on this abstract class definition.
+ * <li>A Facelets ViewHandler instead uses an xml file to define the components and non-component
+ * data that make up a specific view. It stores all of the template content as nodes in the
+ * component tree (wrapping data that is not directly a JSF component in its own special
+ * component classes). Rendering a view is then just a matter of walking the component tree.
+ * </ul>
+ * Of course there is no reason why the "template" needs to be a textual file. A view could
+ * be generated based on data in a database, or many other mechanisms.
+ * <p>
+ * This class is expected to be invoked via the concrete implementation of
+ * {@link javax.faces.lifecycle.Lifecycle}.
+ * <p>
+ * For the official specification for this class, see
+ * <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a>.
*
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
@@ -33,27 +67,128 @@
public static final String DEFAULT_SUFFIX_PARAM_NAME = "javax.faces.DEFAULT_SUFFIX";
public static final String DEFAULT_SUFFIX = ".jsp";
+ /**
+ * Return the Locale object that should be used when rendering this view to the
+ * current user.
+ * <p>
+ * Some request protocols allow an application user to specify what locale they prefer
+ * the response to be in. For example, HTTP requests can specify the "accept-language"
+ * header.
+ * <p>
+ * Method {@link javax.faces.application.Application#getSupportedLocales()} defines
+ * what locales this JSF application is capable of supporting.
+ * <p>
+ * This method should match such sources of data up and return the Locale object that
+ * is the best choice for rendering the current application to the current user.
+ */
public abstract Locale calculateLocale(javax.faces.context.FacesContext context);
+ /**
+ * Return the id of an available render-kit that should be used to map the JSF
+ * components into user presentation.
+ * <p>
+ * The render-kit selected (eg html, xhtml, pdf, xul, ...) may depend upon the user,
+ * properties associated with the request, etc.
+ */
public abstract String calculateRenderKitId(javax.faces.context.FacesContext context);
+ /**
+ * Build a component tree using some kind of view template which is identified by the
+ * viewId parameter.
+ * <p>
+ * Note that the template file may also contain non-component content that should be
+ * mixed in with the components when the view is rendered. Whether JSF components are
+ * created to wrap such data, or the ViewHandler uses some other mechanism to merge
+ * this content in with the component output at render time is left to the ViewHandler
+ * implementation.
+ */
public abstract javax.faces.component.UIViewRoot createView(javax.faces.context.FacesContext context,
String viewId);
+ /**
+ * Return a URL that a remote system can invoke in order to access the specified view.
+ */
public abstract String getActionURL(javax.faces.context.FacesContext context,
String viewId);
+ /**
+ * Return a URL that a remote system can invoke in order to access the specified resource..
+ */
public abstract String getResourceURL(javax.faces.context.FacesContext context,
String path);
+ /**
+ * Combine the output of all the components in the viewToRender with data from the
+ * original view template (if any) and write the result to context.externalContext.response.
+ * <p>
+ * Component output is generated by invoking the encodeBegin, encodeChildren (optional)
+ * and encodeEnd methods on relevant components in the specified view. How this is
+ * interleaved with the non-component content of the view template (if any) is left
+ * to the ViewHandler implementation.
+ * <p>
+ * The actual type of the Response object depends upon the concrete implementation of
+ * this class. It will almost certainly be an OutputStream of some sort, but may be
+ * specific to the particular request/response system in use.
+ * <p>
+ * If the view cannot be rendered (eg due to an error in a component) then a FacesException
+ * is thrown.
+ */
public abstract void renderView(javax.faces.context.FacesContext context,
javax.faces.component.UIViewRoot viewToRender)
throws java.io.IOException,
FacesException;
+ /**
+ * Handle a "postback" request by recreating the component tree that was most recently
+ * presented to the user for the specified view.
+ * <p>
+ * When the user performs a "postback" of a view that has previously been created, ie
+ * is updating the state of an existing view tree, then the view handler must recreate
+ * a view tree identical to the one used previously to render that view to the user,
+ * so that the data received from the user can be compared to the old state and the
+ * correct "changes" detected.
+ * <p>
+ * The components in this tree will then be given the opportunity to examine new input
+ * data provided by the user, and react in the appropriate manner for that component,
+ * as specified for the JSF lifecycle.
+ * <p>
+ * Much of the work required by this method <i>must</i> be delegated to an instance
+ * of StateManager.
+ * <p>
+ * If there is no record of the current user having been sent the specified view
+ * (ie no saved state information available), then NULL should be returned.
+ * <p>
+ * Note that input data provided by the user may also be used to determine exactly
+ * how to restore this view. In the case of "client side state", information
+ * about the components to be restored will be available here. Even for
+ * "server side state", user input may include an indicator that is used to
+ * select among a number of different saved states available for this viewId and
+ * this user.
+ * <p>
+ * Note that data received from users is inherently untrustworthy; care should be
+ * taken to validate this information appropriately.
+ * <p>
+ * See saveState for more details.
+ */
public abstract javax.faces.component.UIViewRoot restoreView(javax.faces.context.FacesContext context,
String viewId);
+ /**
+ * Write sufficient information to context.externalContext.response in order to
+ * be able to restore this view if the user performs a "postback" using that
+ * rendered response.
+ * <p>
+ * For "client side state saving", sufficient information about the view
+ * state should be written to allow a "restore view" operation to succeed
+ * later. This does not necessarily mean storing <i>all</i> data about the
+ * current view; only data that cannot be recreated from the "template" for
+ * this view needs to be saved.
+ * <p>
+ * For "server side state saving", this method may write out nothing. Alternately
+ * it may write out a "state identifier" to identify which of multiple saved
+ * user states for a particular view should be selected (or just verify that the
+ * saved state does indeed correspond to the expected one).
+ */
public abstract void writeState(javax.faces.context.FacesContext context)
throws java.io.IOException;
}