Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.faces.view
Class ViewDeclarationLanguage

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

    public abstract class ViewDeclarationLanguage

extends java.lang.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

Field Summary
`static java.lang.String` | `FACELETS_VIEW_DECLARATION_LANGUAGE_ID` Identifier for the Facelets view declaration language.
`static java.lang.String` | `JSP_VIEW_DECLARATION_LANGUAGE_ID` Identifier for the JSP view declaration language.

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, java.lang.String viewId)` Create a `UIViewRoot` from the VDL contained in the artifact referenced by the argument `viewId`.
`abstract java.beans.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.
`java.lang.String` | `getId()` Returns a non-null String that can be used to identify this view declaration language.
`abstract Resource` | `getScriptComponentResource(FacesContext context, Resource componentResource)` Take implementation specific action to discover a `Resource` given the argument `componentResource`.
`abstract StateManagementStrategy` | `getStateManagementStrategy(FacesContext context, java.lang.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, java.lang.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 argument`view`.
`abstract UIViewRoot` | `restoreView(FacesContext context, java.lang.String viewId)` Restore a `UIViewRoot` from a previously created view.
`void` | `retargetAttachedObjects(FacesContext context, UIComponent topLevelComponent, java.util.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.
`boolean` | `viewExists(FacesContext context, java.lang.String viewId)` Tests whether a physical resource corresponding to the specified viewId exists.

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

Field Detail

### JSP_VIEW_DECLARATION_LANGUAGE_ID

    public static final java.lang.String JSP_VIEW_DECLARATION_LANGUAGE_ID

  Identifier for the JSP view declaration language.

  Since:
    2.1
  See Also:
    Constant Field Values

### FACELETS_VIEW_DECLARATION_LANGUAGE_ID

    public static final java.lang.String FACELETS_VIEW_DECLARATION_LANGUAGE_ID

  Identifier for the Facelets view declaration language.

  Since:
    2.1
  See Also:
    Constant Field Values

Constructor Detail

### ViewDeclarationLanguage

    public ViewDeclarationLanguage()

Method Detail

### getComponentMetadata

    public abstract java.beans.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:
    `java.lang.NullPointerException` - if any of the arguments are `null`.
    `FacesException` - if there is an error in obtaining the metadata
    `java.lang.UnsupportedOperationException` - if this is a JSP VDL implementation.
  Since:
    2.0

### getViewMetadata

    public abstract ViewMetadata getViewMetadata(FacesContext context,
                                                 java.lang.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:
    `java.lang.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:
    `java.lang.NullPointerException` - if any of the arguments are `null`.
    `FacesException` - if there is an error in obtaining the script component resource
    `java.lang.UnsupportedOperationException` - if this is a JSP VDL implementation.
  Since:
    2.0

### createView

    public abstract UIViewRoot createView(FacesContext context,
                                          java.lang.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:
    `java.lang.NullPointerException` - if any of the arguments are `null`
  Since:
    2.0

### restoreView

    public abstract UIViewRoot restoreView(FacesContext context,
                                           java.lang.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:
    `java.lang.NullPointerException` - if any of the arguments are `null`

### retargetAttachedObjects

    public void retargetAttachedObjects(FacesContext context,
                                        UIComponent topLevelComponent,
                                        java.util.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.

  - Obtain the metadata for the composite component. Currently this entails getting the value of the `UIComponent.BEANINFO_KEY` component attribute, which will be an instance of `BeanInfo`. If the metadata cannot be found, log an error message and return.

  - Get the `BeanDescriptor` from the `BeanInfo`.

  - Get the value of the `AttachedObjectTarget.ATTACHED_OBJECT_TARGETS_KEY` from the `BeanDescriptor`'s `getValue()` method. This will be a `List<`AttachedObjectTarget`>`. Let this be targetList.

  - For each curHandler entry in the argument `handlers`

    - Let forAttributeValue be the return from `AttachedObjectHandler.getFor()`.

    - For each curTarget entry in targetList, the first of the following items that causes a match will take this action:

      For each `UIComponent` in the list returned from curTarget.getTargets(), call curHandler.applyAttachedObject(), passing the `FacesContext` and the `UIComponent`.

      and cause this inner loop to terminate.

      - If curHandler is an instance of `ActionSource2AttachedObjectHandler` and curTarget is an instance of `ActionSource2AttachedObjectTarget`, and curTarget.getName() is equal to curTargetName, consider it a match.

      - If curHandler is an instance of `EditableValueHolderAttachedObjectHandler` and curTarget is an instance of `EditableValueHolderAttachedObjectTarget`, and curTarget.getName() is equal to curTargetName, consider it a match.

      - If curHandler is an instance of `ValueHolderAttachedObjectHandler` and curTarget is an instance of `ValueHolderAttachedObjectTarget`, and curTarget.getName() is equal to curTargetName, consider it a match.

      - If curHandler is an instance of `BehaviorHolderAttachedObjectHandler` and curTarget is an instance of `BehaviorHolderAttachedObjectTarget`, and either of the following conditions are true,

        - curHandler.getEventName() is not `null` and is equal to curTargetName.
        - curHandler.getEventName() is `null` and curTarget.isDefaultEvent() is `true`.

        consider it a match.

  The implementation must support retargeting attached objects from the top level compsite component to targets that are composite and non-composite components.

  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:
    `java.lang.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:
    `java.lang.NullPointerException` - if `context` or `topLevelComponent` is `null`.
  Since:
    2.0

### buildView

    public abstract void buildView(FacesContext context,
                                   UIViewRoot root)
                            throws java.io.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 `PhaseListener.afterPhase(javax.faces.event.PhaseEvent)` method of any `PhaseListener`s attached to the application is called

  - The `UIViewRoot` phase listener installed via `UIViewRoot.setAfterPhaseListener(javax.el.MethodExpression)` or `UIViewRoot.addPhaseListener(javax.faces.event.PhaseListener)` are called.

  If the `root` is already populated with children, the view must still be re-built, but care must be taken to ensure that the existing components are correctly paired up with their VDL counterparts in the VDL page. Also, any system events that would normally be generated during the adding or removing of components from the view must be temporarily disabled during the creation of the view and then re-enabled when the view has been built.

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

### renderView

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

  Render a view rooted at argument`view`. 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:
    `java.lang.NullPointerException` - if any of the arguments are `null`
    `java.io.IOException`

### getStateManagementStrategy

    public abstract StateManagementStrategy getStateManagementStrategy(FacesContext context,
                                                                       java.lang.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

### viewExists

    public boolean viewExists(FacesContext context,
                              java.lang.String viewId)

  Tests whether a physical resource corresponding to the specified viewId exists.

  The default implementation uses `ExternalContext.getResource()` to locate the physical resource.

  Parameters:
    `context` - The `FacesContext` for this request.
    `viewId` - the view id to test
  Since:
    2.1

### getId

    public java.lang.String getId()

  Returns a non-null String that can be used to identify this view declaration language.

  The default implementation returns the fully qualified class name of the view declaration language implementation. Subclasses may override to provide a more meaningful id.

  Since:
    2.1

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2002-2010 Oracle America Inc, Inc. All Rights Reserved.