org.apache.tapestry5.internal.structure

## Class ComponentPageElementImpl

- java.lang.Object
- - org.apache.tapestry5.ioc.BaseLocatable
  - - org.apache.tapestry5.internal.structure.ComponentPageElementImpl

- All Implemented Interfaces:
    ComponentResourcesCommon, InternalComponentResourcesCommon, BodyPageElement, ComponentPageElement, Locatable, RenderCommand

      public class ComponentPageElementImpl
      extends BaseLocatable
      implements ComponentPageElement

  Implements `RenderCommand` and represents a component within an overall page. Much of a component page element's behavior is delegated to user code, via a `Component` instance. Once instantiated, a ComponentPageElement should be registered as a lifecycle listener. This could be done inside the constructors, but that tends to complicate unit tests, so its done by `PageElementFactoryImpl`. There's still a bit of refactoring in this class (and its many inner classes) that can improve overall efficiency. Modified for Tapestry 5.2 to adjust for the no-pooling approach (shared instances with externalized mutable state).

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ComponentPageElementImpl(Page page, Instantiator instantiator, ComponentPageElementResources elementResources)` Constructor for the root component of a page.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addBlock(String blockId, Block block)` Used during the contruction of a page to add a non-anonymous Block to the component.
    `void` | `addMixin(String mixinId, Instantiator instantiator, String... order)` Adds a mixin.
    `void` | `addToBody(RenderCommand element)` Used during the construction of the page.
    `void` | `addToTemplate(RenderCommand element)` Used during the construction of a page.
    `void` | `bindMixinParameter(String mixinId, String parameterName, Binding binding)`
    `void` | `bindParameter(String parameterName, Binding binding)` Used during construction of the page to identify the binding for a particular parameter.
    `Link` | `createEventLink(String eventType, Object... context)` Creates a component event request link as a callback for this component.
    `Link` | `createFormEventLink(String eventType, Object... context)` Creates a component event request link as a callback for this component.
    `protected RenderPhaseEvent` | `createRenderEvent(RenderQueue queue)`
    `boolean` | `dispatchEvent(ComponentEvent event)` Asks each mixin and component to `Component.dispatchComponentEvent(ComponentEvent)`, returning true if any handler was found.
    `void` | `enqueueBeforeRenderBody(RenderQueue queue)` Invoked when the component should render its body.
    `Block` | `findBlock(String id)` As with `ComponentResourcesCommon.getBlock(String)`, but returns null if the block is not found.
    `Binding` | `getBinding(String parameterName)` Returns the binding for the given parameter name, or null.
    `Block` | `getBlock(String id)` Returns a block from the component's template, referenced by its id.
    `Block` | `getBody()` Returns the body of this component as a (possibly empty) block.
    `String` | `getCompleteId()` Returns a string consisting of the logical name of the containing page, and the `nested id` of this component, separated by a colon.
    `Component` | `getComponent()` Returns the core component associated with this page element (as opposed to any mixins attached to the component).
    `InternalComponentResources` | `getComponentResources()` Returns the resources associated with the core component.
    `ComponentPageElement` | `getContainerElement()` Containing component (or null for the root component of a page).
    `Page` | `getContainingPage()` Returns the page which contains this component.
    `String` | `getElementName(String defaultElementName)` Returns the name of element that represents the component in its template, or the provided default element name if the element was a component type (in the Tapestry namespace).
    `ComponentPageElement` | `getEmbeddedElement(String embeddedId)` Retrieves a component page element by its id.
    `org.slf4j.Logger` | `getEventLogger()` Returns a logger used to for logging event dispatch and event method invocation.
    `String` | `getId()` Returns the simple (or local) id of the component.
    `Map<String,Binding>` | `getInformalParameterBindings()` Constructs a map linking informal parameters to the corresponding bindings.
    `Locale` | `getLocale()` Returns the locale for the page containing this component.
    `org.slf4j.Logger` | `getLogger()` Returns the log instance associated with the component (which is based on the component or mixin's class name).
    `Component` | `getMixinByClassName(String mixinClassName)` Returns the mixin instance for the fully qualfied mixin class name.
    `ComponentResources` | `getMixinResources(String mixinId)` Returns the `ComponentResources` for a mixin attached to this component element.
    `String` | `getNestedId()` Return a string consisting the concatenated ids of all containing components, separated by periods.
    `String` | `getPageName()` Returns the logical name of the page containing this component.
    `ComponentResourceSelector` | `getResourceSelector()` Returns the selector used when constructing the component and its containing page.
    `boolean` | `hasBody()` Returns true if the element has a body and false otherwise.
    `boolean` | `isLoaded()` Returns true if the component has finished loading.
    `boolean` | `isRendering()` Returns true if the component is currently rendering, false otherwise.
    `ComponentPageElement` | `newChild(String id, String nestedId, String completeId, String elementName, Instantiator instantiator, Location location)` Creates a new child component of the invoked component.
    `void` | `render(MarkupWriter writer, RenderQueue queue)` Pushes the SetupRender phase state onto the queue.
    `String` | `toString()`
    `boolean` | `triggerContextEvent(String eventType, EventContext context, ComponentEventCallback callback)` Triggers a component event.
    `boolean` | `triggerEvent(String eventType, Object[] contextValues, ComponentEventCallback callback)` A convenience method for invoking `ComponentResourcesCommon.triggerContextEvent(String, EventContext , ComponentEventCallback)`.

    - ### Methods inherited from class org.apache.tapestry5.ioc.BaseLocatable

      `getLocation`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.apache.tapestry5.ioc.Locatable

      `getLocation`

- - ### Constructor Detail

    - #### ComponentPageElementImpl

          public ComponentPageElementImpl(Page page,
                                          Instantiator instantiator,
                                          ComponentPageElementResources elementResources)

      Constructor for the root component of a page.

  - ### Method Detail

    - #### newChild

          public ComponentPageElement newChild(String id,
                                               String nestedId,
                                               String completeId,
                                               String elementName,
                                               Instantiator instantiator,
                                               Location location)

      Description copied from interface: `ComponentPageElement`
      Creates a new child component of the invoked component. The new element will be added as an embedded element of its container.
      Specified by:
        `newChild` in interface `ComponentPageElement`
      Parameters:
        `id` - simple id of the new component
        `elementName` - name of the component's element in its container's template
        `instantiator` - used to create a component instance, and access the component's model
        `location` - location of the element within its container's template @return the new component

    - #### addMixin

          public void addMixin(String mixinId,
                               Instantiator instantiator,
                               String... order)

      Description copied from interface: `ComponentPageElement`
      Adds a mixin.
      Specified by:
        `addMixin` in interface `ComponentPageElement`
      Parameters:
        `mixinId` - a unique id for the mixin, the last term of the mixin's class name
        `instantiator` - used to instantiate an instance of the mixin
        `order` - Ordering strings used to determine the order of mixin execution.

    - #### bindMixinParameter

          public void bindMixinParameter(String mixinId,
                                         String parameterName,
                                         Binding binding)

      Specified by:
        `bindMixinParameter` in interface `ComponentPageElement`
      Parameters:
        `mixinId` - id of previously added mixin
        `parameterName` - simple (unqualified) name of parameter
        `binding` - binding for parameter

    - #### getBinding

          public Binding getBinding(String parameterName)

      Description copied from interface: `InternalComponentResourcesCommon`
      Returns the binding for the given parameter name, or null.
      Specified by:
        `getBinding` in interface `InternalComponentResourcesCommon`
      Parameters:
        `parameterName` - name of component parameter
      Returns:
        binding if bound, or null

    - #### bindParameter

          public void bindParameter(String parameterName,
                                    Binding binding)

      Description copied from interface: `InternalComponentResourcesCommon`
      Used during construction of the page to identify the binding for a particular parameter.
      Specified by:
        `bindParameter` in interface `InternalComponentResourcesCommon`

    - #### addToBody

          public void addToBody(RenderCommand element)

      Description copied from interface: `BodyPageElement`
      Used during the construction of the page. Adds a page element as part of the body of the component. The body of a component is defined as the portion of the container's template directly enclosed by component's start and end elements.
      Specified by:
        `addToBody` in interface `BodyPageElement`

    - #### addToTemplate

          public void addToTemplate(RenderCommand element)

      Description copied from interface: `ComponentPageElement`
      Used during the construction of a page. Adds a page element as part of the template for this page element. A page element will eventually render by sequentially rendering these elements. A page elements template is really just the outermost portions of the component's template ... where a template contains elements that are all components, those components will receive portions of the template as their body.
      Specified by:
        `addToTemplate` in interface `ComponentPageElement`

    - #### enqueueBeforeRenderBody

          public void enqueueBeforeRenderBody(RenderQueue queue)

      Description copied from interface: `ComponentPageElement`
      Invoked when the component should render its body.
      Specified by:
        `enqueueBeforeRenderBody` in interface `ComponentPageElement`

    - #### getCompleteId

          public String getCompleteId()

      Description copied from interface: `ComponentResourcesCommon`
      Returns a string consisting of the logical name of the containing page, and the `nested id` of this component, separated by a colon. I.e., "MyPage:foo.bar.baz". For a page, returns just the page's name. This value is often used to obtain an equivalent component instance in a later request.
      Specified by:
        `getCompleteId` in interface `ComponentResourcesCommon`
      See Also:
        `ComponentSource.getComponent(String)`

    - #### getComponent

          public Component getComponent()

      Description copied from interface: `ComponentPageElement`
      Returns the core component associated with this page element (as opposed to any mixins attached to the component).
      Specified by:
        `getComponent` in interface `ComponentPageElement`

    - #### getComponentResources

          public InternalComponentResources getComponentResources()

      Description copied from interface: `ComponentPageElement`
      Returns the resources associated with the core component.
      Specified by:
        `getComponentResources` in interface `ComponentPageElement`

    - #### getContainerElement

          public ComponentPageElement getContainerElement()

      Description copied from interface: `ComponentPageElement`
      Containing component (or null for the root component of a page).
      Specified by:
        `getContainerElement` in interface `ComponentPageElement`

    - #### getContainingPage

          public Page getContainingPage()

      Description copied from interface: `ComponentPageElement`
      Returns the page which contains this component.
      Specified by:
        `getContainingPage` in interface `ComponentPageElement`

    - #### getEmbeddedElement

          public ComponentPageElement getEmbeddedElement(String embeddedId)

      Description copied from interface: `ComponentPageElement`
      Retrieves a component page element by its id. The search is caseless.
      Specified by:
        `getEmbeddedElement` in interface `ComponentPageElement`
      Parameters:
        `embeddedId` - used to locate the element
      Returns:
        the page element

    - #### getId

          public String getId()

      Description copied from interface: `ComponentResourcesCommon`
      Returns the simple (or local) id of the component. The id will be unique within the component's immediate container. For a page's root component, the value null is returned.
      Specified by:
        `getId` in interface `ComponentResourcesCommon`

    - #### getLogger

          public org.slf4j.Logger getLogger()

      Description copied from interface: `ComponentResourcesCommon`
      Returns the log instance associated with the component (which is based on the component or mixin's class name).
      Specified by:
        `getLogger` in interface `ComponentResourcesCommon`
      See Also:
        `ComponentModel.getLogger()`

    - #### getMixinByClassName

          public Component getMixinByClassName(String mixinClassName)

      Description copied from interface: `InternalComponentResourcesCommon`
      Returns the mixin instance for the fully qualfied mixin class name.
      Specified by:
        `getMixinByClassName` in interface `InternalComponentResourcesCommon`
      Parameters:
        `mixinClassName` - fully qualified class name
      Returns:
        IllegalArgumentException if no such mixin is associated with the core component

    - #### getMixinResources

          public ComponentResources getMixinResources(String mixinId)

      Description copied from interface: `ComponentPageElement`
      Returns the `ComponentResources` for a mixin attached to this component element. Mixin ids are the simple names of the mixin class.
      Specified by:
        `getMixinResources` in interface `ComponentPageElement`
      Parameters:
        `mixinId` - the mixin id (case insensitive)
      Returns:
        the resources for the component

    - #### getNestedId

          public String getNestedId()

      Description copied from interface: `ComponentResourcesCommon`
      Return a string consisting the concatenated ids of all containing components, separated by periods. In addition, nested ids are always all lower case. I.e., "foo.bar.baz". Returns null for the root component of a page.
      Specified by:
        `getNestedId` in interface `ComponentResourcesCommon`

    - #### dispatchEvent

          public boolean dispatchEvent(ComponentEvent event)

      Description copied from interface: `ComponentPageElement`
      Asks each mixin and component to `Component.dispatchComponentEvent(ComponentEvent)`, returning true if any handler was found.
      Specified by:
        `dispatchEvent` in interface `ComponentPageElement`
      Parameters:
        `event` - to be handled
      Returns:
        true if a handler was found

    - #### isLoaded

          public boolean isLoaded()

      Description copied from interface: `InternalComponentResourcesCommon`
      Returns true if the component has finished loading. Initially, this value will be false.
      Specified by:
        `isLoaded` in interface `InternalComponentResourcesCommon`
      See Also:
        `PageLifecycleListener.containingPageDidLoad()`

    - #### isRendering

          public boolean isRendering()

      Description copied from interface: `ComponentResourcesCommon`
      Returns true if the component is currently rendering, false otherwise. This is most often used to determine if parameter values should be cached.
      Specified by:
        `isRendering` in interface `ComponentResourcesCommon`

    - #### render

          public final void render(MarkupWriter writer,
                                   RenderQueue queue)

      Pushes the SetupRender phase state onto the queue.
      Specified by:
        `render` in interface `RenderCommand`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### triggerEvent

          public boolean triggerEvent(String eventType,
                                      Object[] contextValues,
                                      ComponentEventCallback callback)

      Description copied from interface: `ComponentResourcesCommon`
      A convenience method for invoking `ComponentResourcesCommon.triggerContextEvent(String, EventContext , ComponentEventCallback)`. Wraps the context values into an `EventContext`.
      Specified by:
        `triggerEvent` in interface `ComponentResourcesCommon`
      Parameters:
        `eventType` - event type (as determined from the request, or otherwise by design)
        `contextValues` - Values that may be provided to the event handler method as method parameters, or null if no context values are available
        `callback` - the handler to be informed of the result, or null if the event is a notification that does not support return values from event handler methods (the value true is allowed even if the handler is null).
      Returns:
        true if any event handler was invoked (even if no event handler method returns a non-null value)
      See Also:
        `OnEventWorker`, `OnEvent`

    - #### triggerContextEvent

          public boolean triggerContextEvent(String eventType,
                                             EventContext context,
                                             ComponentEventCallback callback)

      Description copied from interface: `ComponentResourcesCommon`
      Triggers a component event. A search for an event handling method will occur, first in the component, then its container, and so on. When a matching event handler method is located, it is invoked. If the method returns a value, the value is passed to the callback (if callback is null, then it is an error for a method to return a non-null value). Resolution of event type to event handler methods is case insensitive.
      Specified by:
        `triggerContextEvent` in interface `ComponentResourcesCommon`
      Parameters:
        `eventType` - event type (as determined from the request, or otherwise by design)
        `context` - the context (as extracted from the request, or provided by the triggering component); these values may be provided to event handler methods via their parameters (may not be null)
        `callback` - the handler to be informed of the result, or null if the event is a notification that does not support return values from event handler methods (the value true is allowed even if the handler is null).
      Returns:
        true if any event handler was invoked (even if no event handler method returns a non-null value)
      See Also:
        `OnEventWorker`, `OnEvent`

    - #### getLocale

          public Locale getLocale()

      Description copied from interface: `ComponentResourcesCommon`
      Returns the locale for the page containing this component.
      Specified by:
        `getLocale` in interface `ComponentResourcesCommon`
      See Also:
        `ComponentResourcesCommon.getResourceSelector()`

    - #### getElementName

          public String getElementName(String defaultElementName)

      Description copied from interface: `ComponentResourcesCommon`
      Returns the name of element that represents the component in its template, or the provided default element name if the element was a component type (in the Tapestry namespace).
      Specified by:
        `getElementName` in interface `ComponentResourcesCommon`
      Parameters:
        `defaultElementName` - element name to return if the element name is not known (may be null)
      Returns:
        the element name

    - #### getBlock

          public Block getBlock(String id)

      Description copied from interface: `ComponentResourcesCommon`
      Returns a block from the component's template, referenced by its id.
      Specified by:
        `getBlock` in interface `ComponentResourcesCommon`
      Parameters:
        `id` - the id of the block (case insensitive)
      Returns:
        the identified Block
      See Also:
        `ComponentResourcesCommon.findBlock(String)`

    - #### findBlock

          public Block findBlock(String id)

      Description copied from interface: `ComponentResourcesCommon`
      As with `ComponentResourcesCommon.getBlock(String)`, but returns null if the block is not found.
      Specified by:
        `findBlock` in interface `ComponentResourcesCommon`
      Parameters:
        `id` - the id of the block (case insensitive)
      Returns:
        the block, or null

    - #### addBlock

          public void addBlock(String blockId,
                               Block block)

      Description copied from interface: `ComponentPageElement`
      Used during the contruction of a page to add a non-anonymous Block to the component.
      Specified by:
        `addBlock` in interface `ComponentPageElement`
      See Also:
        `ComponentResourcesCommon.getBlock(String)`

    - #### getPageName

          public String getPageName()

      Description copied from interface: `ComponentResourcesCommon`
      Returns the logical name of the page containing this component. This is the short name (it often appears in URLs)
      Specified by:
        `getPageName` in interface `ComponentResourcesCommon`
      Returns:
        the logical name of the page which contains this component

    - #### hasBody

          public boolean hasBody()

      Description copied from interface: `ComponentResourcesCommon`
      Returns true if the element has a body and false otherwise. Only components may have a body; pages and mixins will return false.
      Specified by:
        `hasBody` in interface `ComponentResourcesCommon`

    - #### getBody

          public Block getBody()

      Description copied from interface: `ComponentResourcesCommon`
      Returns the body of this component as a (possibly empty) block. When invoked on a mixin, returns the containing component's body.
      Specified by:
        `getBody` in interface `ComponentResourcesCommon`

    - #### getInformalParameterBindings

          public Map<String,Binding> getInformalParameterBindings()

      Description copied from interface: `InternalComponentResourcesCommon`
      Constructs a map linking informal parameters to the corresponding bindings.
      Specified by:
        `getInformalParameterBindings` in interface `InternalComponentResourcesCommon`
      Returns:
        map, possible empty

    - #### getEventLogger

          public org.slf4j.Logger getEventLogger()

      Description copied from interface: `ComponentPageElement`
      Returns a logger used to for logging event dispatch and event method invocation.
      Specified by:
        `getEventLogger` in interface `ComponentPageElement`

    - #### createEventLink

          public Link createEventLink(String eventType,
                                      Object... context)

      Description copied from interface: `ComponentResourcesCommon`
      Creates a component event request link as a callback for this component. The event type and context (as well as the page name and nested component id) will be encoded into a URL. A request for the URL will ComponentResourcesCommon.triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback) trigger} the named event on the component.
      Specified by:
        `createEventLink` in interface `ComponentResourcesCommon`
      Parameters:
        `eventType` - the type of event to be triggered. Event types should be Java identifiers (contain only letters, numbers and the underscore).
        `context` - additional objects to be encoded into the path portion of the link; each is converted to a string and URI encoded
      Returns:
        link object for the callback

    - #### createFormEventLink

          public Link createFormEventLink(String eventType,
                                          Object... context)

      Description copied from interface: `ComponentResourcesCommon`
      Creates a component event request link as a callback for this component. The event type and context (as well as the page name and nested component id) will be encoded into a URL. A request for the URL will ComponentResourcesCommon.triggerEvent(String, Object[], org.apache.tapestry5.ComponentEventCallback) trigger} the named event on the component. This is only used for form submission events, as extra data may be encoded in the form as hidden fields.
      Specified by:
        `createFormEventLink` in interface `ComponentResourcesCommon`
      Parameters:
        `eventType` - the type of event to be triggered. Event types should be Java identifiers (contain only letters, numbers and the underscore).
        `context` - additional objects to be encoded into the path portion of the link; each is converted to a string and URI encoded
      Returns:
        link object for the callback

    - #### createRenderEvent

          protected RenderPhaseEvent createRenderEvent(RenderQueue queue)

    - #### getResourceSelector

          public ComponentResourceSelector getResourceSelector()

      Description copied from interface: `ComponentResourcesCommon`
      Returns the selector used when constructing the component and its containing page.
      Specified by:
        `getResourceSelector` in interface `ComponentResourcesCommon`

${project.version} - Copyright © 2003-2015 The Apache Software Foundation.