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 23:15:28 UTC
svn commit: r589218 - in
/myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application:
StateManager.java ViewHandler.java
Author: skitching
Date: Sat Oct 27 14:15:28 2007
New Revision: 589218
URL: http://svn.apache.org/viewvc?rev=589218&view=rev
Log:
Add documentation only
Modified:
myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/StateManager.java
myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/ViewHandler.java
Modified: myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/StateManager.java
URL: http://svn.apache.org/viewvc/myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/StateManager.java?rev=589218&r1=589217&r2=589218&view=diff
==============================================================================
--- myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/StateManager.java (original)
+++ myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/StateManager.java Sat Oct 27 14:15:28 2007
@@ -20,7 +20,34 @@
/**
- * see Javadoc of <a href="http://java.sun.com/javaee/javaserverfaces/1.2/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 also the <a href="http://java.sun.com/javaee/javaserverfaces/1.2/docs/api/index.html">JSF Specification</a>
*
* @author Manfred Geiler (latest modification by $Author$)
* @author Stan Silvert
@@ -34,6 +61,11 @@
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.
+ * <p>
+ * Deprecated; use saveView instead.
+ *
* @deprecated
*/
public StateManager.SerializedView saveSerializedView(javax.faces.context.FacesContext context) {
@@ -41,6 +73,11 @@
}
/**
+ * Returns an object that is sufficient to recreate the component tree that is the viewroot of
+ * the specified context.
+ * <p>
+ * The return value is suitable for passing to method writeState.
+ *
* @since 1.2
*/
public Object saveView(FacesContext context) {
@@ -55,6 +92,15 @@
}
/**
+ * 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.
+ * <p>
+ * Deprecated; use saveView instead.
+ *
* @deprecated
*/
protected Object getTreeStructureToSave(javax.faces.context.FacesContext context) {
@@ -62,6 +108,11 @@
}
/**
+ * Return data that can be applied to a component tree created using the "getTreeStructureToSave"
+ * method.
+ * <p>
+ * Deprecated; use saveView instead.
+ *
* @deprecated
*/
protected Object getComponentStateToSave(javax.faces.context.FacesContext context) {
@@ -69,6 +120,18 @@
}
/**
+ * 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.
+ * <p>
+ * Deprecated; use writeState(FacesContext, Object) instead. This method was abstract
+ * in JSF1.1, but is now an empty non-abstract method so that old classes that implement
+ * this method continue to work, while new classes can just override the new writeState
+ * method rather than this one.
+ *
* @deprecated
*/
public void writeState(javax.faces.context.FacesContext context,
@@ -78,6 +141,17 @@
}
/**
+ * 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.
+ * <p>
+ * This method should be overridden by subclasses. It is not abstract because a default
+ * implementation is provided that forwards to the old writeState method; this allows
+ * subclasses of StateManager written using the JSF1.1 API to continue to work.
+ * <p>
* @since 1.2
*/
public void writeState(FacesContext context, Object state) throws IOException {
Modified: myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/ViewHandler.java
URL: http://svn.apache.org/viewvc/myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/ViewHandler.java?rev=589218&r1=589217&r2=589218&view=diff
==============================================================================
--- myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/ViewHandler.java (original)
+++ myfaces/core/branches/1_2_1/api/src/main/java/javax/faces/application/ViewHandler.java Sat Oct 27 14:15:28 2007
@@ -22,7 +22,39 @@
import java.util.Locale;
/**
- * see Javadoc of <a href="http://java.sun.com/javaee/javaserverfaces/1.2/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 responsible 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.
+ * </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/javaee/javaserverfaces/1.2/docs/api/index.html">JSF Specification</a>.
*
* @author Manfred Geiler (latest modification by $Author$)
* @version $Revision$ $Date$
@@ -63,16 +95,55 @@
return _encoding;
}
+ /**
+ * 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 root node for a component tree.
+ * <p>
+ * When a request is received, this method is called if restoreView returns null,
+ * ie this is not a "postback". In this case, a root node is created and then renderView
+ * is invoked. It is the responsibility of the renderView method to build the full
+ * component tree (ie populate the UIViewRoot with descendant nodes).
+ * <p>
+ * This method is also invoked when navigation occurs from one view to another, where
+ * the viewId passed is the id of the new view to be displayed. Again it is the responsibility
+ * of renderView to then populate the viewroot with descendants.
+ */
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);
@@ -98,14 +169,85 @@
}
}
+ /**
+ * 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.
+ * <p>
+ * Note that if a "postback" has occurred but no navigation to a different view, then
+ * the viewToRender will be fully populated with components already. However on direct
+ * access to a new view, or when navigation has occurred, the viewToRender will just
+ * contain an empty UIViewRoot object that must be populated with components from
+ * the "view template".
+ */
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 (well, actually only those components that respond to
+ * input are actually needed before the render phase).
+ * <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 writeState 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;
}