javax.faces.view
Class ViewDeclarationLanguage

java.lang.Object
  extended by javax.faces.view.ViewDeclarationLanguage

public abstract class ViewDeclarationLanguage
extends Object

The contract that a view declaration language must implement to interact with the JSF runtime. An implementation of this class must be thread-safe.

Instances of this class are application scoped and must be obtained from the ViewDeclarationLanguageFactory.

Since:
2.0

Constructor Summary
ViewDeclarationLanguage()
           
 
Method Summary
abstract  void buildView(FacesContext context, UIViewRoot root)
          

Take any actions specific to this VDL implementation to cause the argument UIViewRoot which must have been created via a call to createView(javax.faces.context.FacesContext, java.lang.String), to be populated with children.

abstract  UIViewRoot createView(FacesContext context, String viewId)
          

Create a UIViewRoot from the VDL contained in the artifact referenced by the argument viewId.

abstract  BeanInfo getComponentMetadata(FacesContext context, Resource componentResource)
          

Return a reference to the component metadata for the composite component represented by the argument componentResource, or null if the metadata cannot be found.

abstract  Resource getScriptComponentResource(FacesContext context, Resource componentResource)
          

Take implementation specific action to discover a Resource given the argument componentResource.

abstract  StateManagementStrategy getStateManagementStrategy(FacesContext context, String viewId)
          

For implementations that want to control the implementation of state saving and restoring, the StateManagementStrategy allows them to do so.

abstract  ViewMetadata getViewMetadata(FacesContext context, String viewId)
          

Return a reference to the view metadata for the view represented by the argument viewId, or null if the metadata cannot be found.

abstract  void renderView(FacesContext context, UIViewRoot view)
          

Render a view rooted at argumentview.

abstract  UIViewRoot restoreView(FacesContext context, String viewId)
          

Restore a UIViewRoot from a previously created view.

 void retargetAttachedObjects(FacesContext context, UIComponent topLevelComponent, List<AttachedObjectHandler> handlers)
          

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting attached objects from the top level composite component to the individual AttachedObjectTarget instances inside the composite component.

 void retargetMethodExpressions(FacesContext context, UIComponent topLevelComponent)
          

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting any method expressions from the top level component to the appropriate inner component.

 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ViewDeclarationLanguage

public ViewDeclarationLanguage()
Method Detail

getComponentMetadata

public abstract BeanInfo getComponentMetadata(FacesContext context,
                                              Resource componentResource)

Return a reference to the component metadata for the composite component represented by the argument componentResource, or null if the metadata cannot be found. See section JSF.7.6.2 for the specification of the default implementation. JSP implementations must throw UnsupportedOperationException.

Parameters:
context - The FacesContext for this request.
componentResource - The Resource that represents the component.
Throws:
NullPointerException - if any of the arguments are null.
FacesException - if there is an error in obtaining the metadata
UnsupportedOperationException - if this is a JSP VDL implementation.
Since:
2.0

getViewMetadata

public abstract ViewMetadata getViewMetadata(FacesContext context,
                                             String viewId)

Return a reference to the view metadata for the view represented by the argument viewId, or null if the metadata cannot be found. See section JSF.7.6.2 for the specification of the default implementation. Facelets for JSF 2 implementation must return non-null. JSP implementations must return null.

Parameters:
context - The FacesContext for this request.
viewId - the view id from whith to extract the metadata
Throws:
NullPointerException - if any of the arguments are null.
FacesException - if there is an error in obtaining the metadata
Since:
2.0

getScriptComponentResource

public abstract Resource getScriptComponentResource(FacesContext context,
                                                    Resource componentResource)

Take implementation specific action to discover a Resource given the argument componentResource. See section JSF.7.6.2 for the specification of the default implementation. JSP implementations must throw UnsupportedOperationException.

Parameters:
context - The FacesContext for this request.
componentResource - The Resource that represents the component.
Throws:
NullPointerException - if any of the arguments are null.
FacesException - if there is an error in obtaining the script component resource
UnsupportedOperationException - if this is a JSP VDL implementation.
Since:
2.0

createView

public abstract UIViewRoot createView(FacesContext context,
                                      String viewId)

Create a UIViewRoot from the VDL contained in the artifact referenced by the argument viewId. See section JSF.7.6.2 for the specification of the default implementation.

Parameters:
context - the FacesContext for this request.
viewId - the identifier of an artifact that contains the VDL syntax that describes this view.
Throws:
NullPointerException - if any of the arguments are null
Since:
2.0

restoreView

public abstract UIViewRoot restoreView(FacesContext context,
                                       String viewId)

Restore a UIViewRoot from a previously created view. See section JSF.7.6.2 for the specification of the default implementation.

Parameters:
context - the FacesContext for this request.
viewId - the identifier for a previously rendered view.
Throws:
NullPointerException - if any of the arguments are null

retargetAttachedObjects

public void retargetAttachedObjects(FacesContext context,
                                    UIComponent topLevelComponent,
                                    List<AttachedObjectHandler> handlers)

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting attached objects from the top level composite component to the individual AttachedObjectTarget instances inside the composite component. This method must be called by the ViewDeclarationLanguage implementation when creating the UIComponent tree when a composite component usage is encountered.

An algorithm semantically equivalent to the following must be implemented.

An implementation is provided that will throw UnsupportedOperationException. A Faces implementation compliant with version 2.0 and beyond of the specification must override this method.

Parameters:
context - the FacesContext for this request.
topLevelComponent - The UIComponent in the view to which the attached objects must be attached. This UIComponent must have its component metadata already associated and available from via the JavaBeans API.
Throws:
NullPointerException - if any of the arguments are null.
Since:
2.0

retargetMethodExpressions

public void retargetMethodExpressions(FacesContext context,
                                      UIComponent topLevelComponent)

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting any method expressions from the top level component to the appropriate inner component. For each attribute that is a MethodExpression (as indicated by the presence of a "method-signature" attribute and the absence of a "type" attribute), the following action must be taken:

  • Get the value of the targets attribute. If the value is a ValueExpression evaluate it. If there is no targets attribute, let the name of the metadata element be the evaluated value of the targets attribute.

  • Interpret targets as a space (not tab) separated list of ids. For each entry in the list:

    • Find the inner component of the topLevelComponent with the id equal to the current list entry. For discussion, this component is called target. If not found, log and error and continue to the next attribute.

    • For discussion the declared name of the attribute is called name.

    • In the attributes map of the topLevelComponent, look up the entry under the key name. Assume the result is a ValueExpression. For discussion, this is attributeValueExpression. If not found, log an error and continue to the next attribute.

    • If name is equal to the string "action", or "actionListener" without the quotes, assume target is an ActionSource2.

    • If name is equal to the string "validator", or "valueChangeListener" without the quotes, assume target is an EditableValueHolder.

    • Call getExpressionString() on the attributeValueExpression and use that string to create a MethodExpression of the appropriate signature for name.

    • If name is not equal to any of the previously listed strings, call getExpressionString() on the attributeValueExpression and use that string to create a MethodExpression where the signature is created based on the value of the "method-signature" attribute of the <composite:attribute /> tag.

    • Let the resultant MethodExpression be called attributeMethodExpression for discussion.

    • If name is equal to the string "action" without the quotes, call ActionSource2.setActionExpression(javax.el.MethodExpression) on target, passing attributeMethodExpression.

    • If name is equal to the string "actionListener" without the quotes, call ActionSource.addActionListener(javax.faces.event.ActionListener) on target, passing attributeMethodExpression wrapped in a MethodExpressionActionListener.

    • If name is equal to the string "validator" without the quotes, call EditableValueHolder.addValidator(javax.faces.validator.Validator) on target, passing attributeMethodExpression wrapped in a MethodExpressionValidator.

    • If name is equal to the string "valueChangeListener" without the quotes, call EditableValueHolder.addValueChangeListener(javax.faces.event.ValueChangeListener) on target, passing attributeMethodExpression wrapped in a MethodExpressionValueChangeListener.

    • Otherwise, assume that the MethodExpression should be placed in the components attribute set. The runtme must create the MethodExpression instance based on the value of the "method-signature" attribute.

An implementation is provided that will throw UnsupportedOperationException. A Faces implementation compliant with version 2.0 and beyond of the specification must override this method.

Parameters:
context - the FacesContext for this request.
topLevelComponent - The UIComponent in the view to which the attached objects must be attached. This UIComponent must have its component metadata already associated and available from via the JavaBeans API.
Throws:
NullPointerException - if context or topLevelComponent is null.
Since:
2.0

buildView

public abstract void buildView(FacesContext context,
                               UIViewRoot root)
                        throws IOException

Take any actions specific to this VDL implementation to cause the argument UIViewRoot which must have been created via a call to createView(javax.faces.context.FacesContext, java.lang.String), to be populated with children.

The Facelets implementation must insure that markup comprising the view must be executed, with the UIComponent instances in the view being encountered in the same depth-first order as in other lifecycle methods defined on UIComponent, and added to the view (but not rendered) during the traversal. The runtime must guarantee that the view must be fully populated before any of the following happen.

The implementation must take no action if the argument root already has non-metadata children. See section JSF.7.6.2.3 for the view metadata specification.

Parameters:
context - the FacesContext for this request
root - the UIViewRoot to populate with children using techniques specific to this VDL implementation.
Throws:
IOException

renderView

public abstract void renderView(FacesContext context,
                                UIViewRoot view)
                         throws IOException

Render a view rooted at argumentview. See section JSF.7.6.2 for the specification of the default implementation.

Parameters:
context - the FacesContext for this request.
view - the UIViewRoot from an early call to createView(javax.faces.context.FacesContext, java.lang.String) or restoreView(javax.faces.context.FacesContext, java.lang.String).
Throws:
NullPointerException - if any of the arguments are null
IOException

getStateManagementStrategy

public abstract StateManagementStrategy getStateManagementStrategy(FacesContext context,
                                                                   String viewId)

For implementations that want to control the implementation of state saving and restoring, the StateManagementStrategy allows them to do so. Returning null indicates that the implementation wishes the runtime to handle the state saving and restoring. Implementations that provide the VDL for Facelets for JSF 2.0 and later must return non-null from this method.

Since:
2.0


Copyright 2002-2009 Sun Microsystems, Inc. All Rights Reserved.