[TRINIDAD][API]More hooks for TRINIDAD-1368 Backport JSF 2.0 Component Tree Visiting and Optimize PPR Rendering

[Blake Sullivan <bl...@oracle.com>]

The first problem we have had is that components need to separate the 
contex6 setup and teardown needed to process their children from the 
context setup and tear down of the components themselves.  For example, 
consider a composite component that establishes an EL context for its 
children--that context should only be setup when the children are being 
processed, not when the component is processing its own attributes.

In the case of encoding, we want to delegate to the Renderer to ensure 
that the setup and teardown of context for child processing is 
consistent between optimized rendering using tree visiting and full 
rendering traversals.

The second problem was that UIXComponent.setUpEncodingContext was named 
differently than all of the other set up methods.  I've made the 
spelling consistent (which after a quick check of the dictionary is 
consitently wrong through out Trinidad setup as a compound word is a 
noun and as a verb is two words, so it should have been setUp.  Drat!) 
and temporarily left a final deprecated version in that I will whack 
shortly.

The third issue is that iterating components often want to modify only 
the manner in which their data is iterated over.  To simplify this, we 
add a hook visitData() to UIXCollection.

-- Blake Sullivan

UIXComponent:

 /**
  * Hook for subclasses to override the manner in which the component's 
children are visited.  The default
  * implementation visits all of the children and facets of the Component.
  * <code>setupChildrenVisitingContext</code> will have been called 
before this method is
  * invoked and <code>tearDownChildrenVisitingContext</code> will be 
called after.
  * respectively.  If the purpose of this visit was to encode the 
component and the
  * component uses a CoreRenderer, the CoreRenderer's
  * <code>setupChildrenEncodingContext</code> and 
<code>tearDownChildrenEncodingContext</code>
  * will be called before and after this method is invoked, respectively.
  * @param visitContext the <code>VisitContext</code> for this visit
  * @param callback the <code>VisitCallback</code> instance
  * @return <code>true</code> if the visit is complete.
  * @see #setupChildrenVisitingContext
  * @see #tearDownChildrenVisitingContext
  * @see 
org.apache.myfaces.trinidad.render.CoreRenderer#setupChildrenEncodingContext
  * @see 
org.apache.myfaces.trinidad.render.CoreRenderer#tearDownChildrenEncodingContext
  */
  protected boolean visitChildren(
    VisitContext visitContext,
    VisitCallback callback)

  /**
   * <p>Sets up the context necessary to visit or invoke the children of 
a component for all phases.
   * </p>
   * <p>The default implementation does nothing.</p>
   * <p>If a subclass overrides this method, it should override
   * <code>tearDownChildrenVisitingContext</code> as well.</p>
   * <p>It is guaranteed that if 
<code>setupChildrenVisitingContext</code> completes
   * <code>tearDownChildrenVisitingContext</code> will be called for 
this component</p>
   * @param context FacesContext
   * @see #visitChildren
   * @see #tearDownChildrenVisitingContext
   */
  protected void 
setupChildrenVisitingContext(@SuppressWarnings("unused") FacesContext 
context)

  /**
   * <p>Tears down context created in order to visit or invoke the 
children of a component
   * for all phases.</p>
   * <p>The default implementation does nothing.</p>
   * <p>A subclass should only override this method if it overrode
   * <code>setupChildrenVisitingContext</code> as well</p>
   * <p>It is guaranteed that 
<code>tearDownChildrenVisitingContext</code> will be called only after
   * <code>setupChildrenVisitingContext</code> has been called for this 
component</p>
   * @param context FacesContext
   * @see #setupChildrenVisitingContext
   * @see #visitChildren
   */
  protected void 
tearDownChildrenVisitingContext(@SuppressWarnings("unused") FacesContext 
context)

CoreRenderer

   * <p>
   * Called before rendering the current component's children in order 
to set
   * up any special context.
   * </p>
   * <p>If <code>setupChildrenEncodingContext</code> succeeds then
   * <code>tearDownChildrenEncodingContext</code> will be called for the 
same component.
   * </p>
   * <p>The default implementation does nothing</p>
   * @param context FacesContext for this request
   * @param rc RenderingContext for this encoding pass
   * @param component Component to encode using this Renderer
   * @see #tearDownChildrenEncodingContext
   */
  public void setupChildrenEncodingContext(
    @SuppressWarnings("unused") FacesContext context,
    @SuppressWarnings("unused") RenderingContext rc,
    @SuppressWarnings("unused") UIComponent component)

  /**
   * <p>
   * Called after rendering the current component's children in order to 
tear
   * down any special context.
   * </p>
   * <p>
   * <code>tearDownChildrenEncodingContext</code> will be called on the 
component if
   * <code>setupChildrenEncodingContext</code> succeeded.
   * </p>
   * <p>The default implementation does nothing</p>
   * @param context FacesContext for this request
   * @param rc RenderingContext for this encoding pass
   * @param component Component to encode using this Renderer
   * @see #setupChildrenEncodingContext
   */
  public void tearDownChildrenEncodingContext(
    @SuppressWarnings("unused") FacesContext context,
    @SuppressWarnings("unused") RenderingContext rc,
    @SuppressWarnings("unused") UIComponent component)

UIXCollection:

  /**
   * Visit the rows and children of the columns of the collection per 
row-index. This should
   * not visit row index -1 (it will be perfomed in the visitTree 
method). The columns
   * themselves should not be visited, only their children in this function.
   *
   * @param visitContext The visiting context
   * @param callback The visit callback
   * @return true if the visiting should stop
   * @see #visitChildren(VisitContext, VisitCallback)
   */
  protected abstract boolean visitData(
    VisitContext  visitContext,
    VisitCallback callback);