Package org.apache.tapestry5.internal.structure

# Class ComponentPageElementImpl

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

All Implemented Interfaces:
  `Locatable`, `ComponentResourcesCommon`, `InternalComponentResourcesCommon`, `BodyPageElement`, `ComponentPageElement`, `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
  Description
  `ComponentPageElementImpl(Page page, Instantiator instantiator, ComponentPageElementResources elementResources)`
  Constructor for the root component of a page.

- ## Method Summary

  Modifier and Type
  Method
  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.
  `Set<String>`
  `getEmbeddedElementIds()`
  Returns the ids of all embedded elements defined within the component.
  `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.
  `final 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.commons.Locatable

  `getLocation`

- ## Constructor Details

  - ### ComponentPageElementImpl

    public ComponentPageElementImpl(Page page, Instantiator instantiator, ComponentPageElementResources elementResources)
    Constructor for the root component of a page.

- ## Method Details

  - ### 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

  - ### getEmbeddedElementIds

    public Set<String> getEmbeddedElementIds()
    Description copied from interface: `ComponentPageElement`
    Returns the ids of all embedded elements defined within the component.
    Specified by:
      `getEmbeddedElementIds` in interface `ComponentPageElement`

  - ### 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`