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

ComponentPageElementImpl(Page page, Instantiator instantiator, ComponentPageElementResources elementResources, Request request, SymbolSource symbolSource)
Constructor for the root component of a page.

Method Summary

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	createActionLink(String eventType, boolean forForm, Object... context) Creates a component event request link as a callback for this component.
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.
Link	createPageLink(Class pageClass, boolean override, Object... context) Creates a page render request link to render a specific page.
Link	createPageLink(String pageName, boolean override, Object... context) Creates a page render request link to render a specific page.
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 concatinated 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 convienience 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,
                                Request request,
                                SymbolSource symbolSource)

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 concatinated 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 convienience 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

createActionLink

public Link createActionLink(String eventType,
                             boolean forForm,
                             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:

createActionLink 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).

forForm - if true, the link will be used as the eventType for an HTML form submission, which may affect what information is encoded into the link

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

createPageLink

public Link createPageLink(String pageName,
                           boolean override,
                           Object... context)

Description copied from interface: ComponentResourcesCommon

Creates a page render request link to render a specific page.

Specified by:

createPageLink in interface ComponentResourcesCommon

Parameters:

pageName - the logical name of the page to link to

override - if true, the context is used even if empty (normally, the target page is allowed to passivate, providing a context, when the provided context is empty)

context - the activation context for the page. If omitted, the activation context is obtained from the target page

Returns:

link for a render request to the targetted page

createPageLink

public Link createPageLink(Class pageClass,
                           boolean override,
                           Object... context)

Description copied from interface: ComponentResourcesCommon

Creates a page render request link to render a specific page. Using a page class, rather than a page name, is more refactoring safe (in the even the page is renamed or moved).

Specified by:

createPageLink in interface ComponentResourcesCommon

Parameters:

pageClass - identifies the page to link to

override - if true, the context is used even if empty (normally, the target page is allowed to passivate, providing a context, when the provided context is empty)

context - the activation context for the page. If omitted, the activation context is obtained from the target page

Returns:

link for a render request to the targetted page

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