org.apache.tapestry
Class AbstractComponent

java.lang.Object
  org.apache.hivemind.impl.BaseLocatable
      org.apache.tapestry.AbstractComponent

All Implemented Interfaces:

org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder, IComponent, IRender

Direct Known Subclasses:

AbstractFormComponent, AbstractLinkComponent, Any, BaseComponent, Block, Body, Card, Conditional, Delegator, Describe, Do, ElseBean, FieldLabel, Foreach, Form, Frame, Image, Image, Input, Insert, InsertText, InvokeListener, OnEvent, Option, Option, PropertySelection, Radio, RenderBlock, RenderBody, Rollover, Script, Select, Setvar, Shell, Timer

public abstract class AbstractComponent
extends org.apache.hivemind.impl.BaseLocatable
implements IComponent

Abstract base class implementing the IComponentinterface.

Author:

Howard Lewis Ship

Constructor Summary

AbstractComponent()

Method Summary

void	addAsset(java.lang.String name, IAsset asset) Adds an asset to the component.
void	addBody(IRender element) Adds an element (which may be static text or a component) as a body element of this component.
void	addComponent(IComponent component) Adds a component to a container.
protected void	checkActiveLock()
protected void	cleanupAfterRender(IRequestCycle cycle) Invoked by render(IMarkupWriter, IRequestCycle)after the component renders.
void	enterActiveState() Invoked after IComponent.finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)to switch the component from its initial construction state into its active state.
protected void	finishLoad() Invoked, as a convienience, from finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).
void	finishLoad(IRequestCycle cycle, IPageLoader loader, IComponentSpecification specification) Invokes finishLoad().
java.lang.String	format(java.lang.String key, java.lang.Object argument) Deprecated. To be removed in 4.1. Use getMessages() instead.
java.lang.String	format(java.lang.String key, java.lang.Object[] arguments) Deprecated. To be removed in 4.1. Use getMessages() instead.
java.lang.String	format(java.lang.String key, java.lang.Object argument1, java.lang.Object argument2) Deprecated. To be removed in 4.1. Use getMessages() instead.
java.lang.String	format(java.lang.String key, java.lang.Object argument1, java.lang.Object argument2, java.lang.Object argument3) Deprecated. To be removed in 4.1. Use getMessages() instead.
IAsset	getAsset(java.lang.String name) Returns the named asset, or null if not found.
java.util.Map	getAssets() Returns the asset map for the component, which may be empty but will not be null.
IBeanProvider	getBeans() Returns the IBeanProviderfor this component.
IBinding	getBinding(java.lang.String name) Returns the named binding, or null if it doesn't exist.
java.util.Collection	getBindingNames() Returns a Collectionof the names of all bindings (which includes bindings for both formal and informal parameters).
java.util.Map	getBindings() Returns an unmodifiable Mapof all bindings for this component.
IRender[]	getBody() Returns the body of the component, the element (which may be static HTML or components) that the component immediately wraps.
int	getBodyCount() Returns the active number of elements in the the body, which may be zero.
IComponent	getComponent(java.lang.String id) Retrieves an contained component by its id.
java.util.Map	getComponents() Returns an unmodifiable Mapof components, keyed on component id.
IContainedComponent	getContainedComponent() Returns the IContainedComponent.
IComponent	getContainer() Returns the component which embeds the receiver.
java.lang.String	getExtendedId() Returns the name of the page, a slash, and this component's id path.
java.lang.String	getId() Returns the simple id of the component, as defined in its specification.
java.lang.String	getIdPath() Returns the qualified id of the component.
ListenerMap	getListeners() Returns a ListenerMap for the component.
java.lang.String	getMessage(java.lang.String key) Deprecated. To be removed in 4.1. Use getMessages() instead.
org.apache.hivemind.Messages	getMessages() Returns component strings for the component.
INamespace	getNamespace() Returns the INamespacein which the component was defined (as an alias).
IPage	getPage() Returns the page which ultimately contains the receiver.
java.lang.Object	getProperty(java.lang.String propertyName) Deprecated.
IComponentSpecification	getSpecification() Returns the specification which defines the component.
protected boolean	isInActiveState() Returns true if the component has been transitioned into its active state by invoking enterActiveState()
boolean	isParameterBound(java.lang.String parameterName) Returns true if the specified parameter is bound.
boolean	isRendering() Returns true if the component is currently rendering.
void	pageEndRender(PageEvent event) Empty implementation of PageEndRenderListener.pageEndRender(PageEvent).
protected void	prepareForRender(IRequestCycle cycle) Invoked by render(IMarkupWriter, IRequestCycle)to prepare the component to render.
void	render(IMarkupWriter writer, IRequestCycle cycle) The main method used to render the component.
void	renderBody(IMarkupWriter writer, IRequestCycle cycle) Renders all elements wrapped by the receiver.
protected abstract void	renderComponent(IMarkupWriter writer, IRequestCycle cycle) Invoked by render(IMarkupWriter, IRequestCycle)to actually render the component (with any parameter values already set).
protected void	renderInformalParameters(IMarkupWriter writer, IRequestCycle cycle) Converts informal parameters into additional attributes on the curently open tag.
void	setBinding(java.lang.String name, IBinding binding) Adds the binding with the given name, replacing any existing binding with that name.
void	setContainedComponent(IContainedComponent containedComponent) Sets the IComponent.getContainedComponent() property; this may only be done once.
void	setContainer(IComponent value) Sets the container of the component.
void	setId(java.lang.String value) Sets the id of the component.
void	setNamespace(INamespace namespace) Sets the INamespacefor the component.
void	setPage(IPage value) Sets the page which ultimiately contains the component.
void	setProperty(java.lang.String propertyName, java.lang.Object value) Deprecated.
java.lang.String	toString()

Methods inherited from class org.apache.hivemind.impl.BaseLocatable

getLocation, setLocation

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.hivemind.LocationHolder

setLocation

Methods inherited from interface org.apache.hivemind.Locatable

getLocation

Constructor Detail

AbstractComponent

public AbstractComponent()

Method Detail

addAsset

public void addAsset(java.lang.String name,
                     IAsset asset)

Description copied from interface: IComponent

Adds an asset to the component. This is invoked from the page loader.

Specified by:

addAsset in interface IComponent

addComponent

public void addComponent(IComponent component)

Description copied from interface: IComponent

Adds a component to a container. Should only be called during the page loading process, which is responsible for any checking.

Specified by:

addComponent in interface IComponent

See Also:

IPageLoader

addBody

public void addBody(IRender element)

Adds an element (which may be static text or a component) as a body element of this component. Such elements are rendered by renderBody(IMarkupWriter, IRequestCycle).

Specified by:

addBody in interface IComponent

Since:

2.2

finishLoad

public void finishLoad(IRequestCycle cycle,
                       IPageLoader loader,
                       IComponentSpecification specification)

Invokes finishLoad(). Subclasses may overide as needed, but must invoke this implementation. BaseComponent loads its HTML template.

Specified by:

finishLoad in interface IComponent

renderInformalParameters

protected void renderInformalParameters(IMarkupWriter writer,
                                        IRequestCycle cycle)

Converts informal parameters into additional attributes on the curently open tag.

Invoked from subclasses to allow additional attributes to be specified within a tag (this works best when there is a one-to-one corespondence between an IComponentand a HTML element.

Iterates through the bindings for this component. Filters out bindings for formal parameters.

For each acceptible key, the value is extracted using IBinding.getObject(). If the value is null, no attribute is written.

If the value is an instance of IAsset, then IAsset.buildURL() is invoked to convert the asset to a URL.

Finally, IMarkupWriter.attribute(String,String)is invoked with the value (or the URL).

The most common use for informal parameters is to support the HTML class attribute (for use with cascading style sheets) and to specify JavaScript event handlers.

Components are only required to generate attributes on the result phase; this can be skipped during the rewind phase.

getBinding

public IBinding getBinding(java.lang.String name)

Returns the named binding, or null if it doesn't exist.

In Tapestry 3.0, it was possible to force a binding to be stored in a component property by defining a concrete or abstract property named "nameBinding" of type IBinding. This has been removed in release 4.0 and bindings are always stored inside a Map of the component.

Specified by:

getBinding in interface IComponent

See Also:

setBinding(String,IBinding)

isParameterBound

public boolean isParameterBound(java.lang.String parameterName)

Returns true if the specified parameter is bound.

Since:

4.0

getComponent

public IComponent getComponent(java.lang.String id)

Description copied from interface: IComponent

Retrieves an contained component by its id. Contained components have unique ids within their container.

Specified by:

getComponent in interface IComponent

getContainer

public IComponent getContainer()

Description copied from interface: IComponent

Returns the component which embeds the receiver. All components are contained within other components, with the exception of the root page component.

A page returns null.

Specified by:

getContainer in interface IComponent

setContainer

public void setContainer(IComponent value)

Description copied from interface: IComponent

Sets the container of the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.

Specified by:

setContainer in interface IComponent

getExtendedId

public java.lang.String getExtendedId()

Returns the name of the page, a slash, and this component's id path. Pages are different, they override this method to simply return their page name.

Specified by:

getExtendedId in interface IComponent

See Also:

getIdPath()

getId

public java.lang.String getId()

Description copied from interface: IComponent

Returns the simple id of the component, as defined in its specification.

An id will be unique within the component which contains this component.

A pagewill always return null.

Specified by:

getId in interface IComponent

setId

public void setId(java.lang.String value)

Description copied from interface: IComponent

Sets the id of the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.

Specified by:

setId in interface IComponent

getIdPath

public java.lang.String getIdPath()

Description copied from interface: IComponent

Returns the qualified id of the component. This represents a path from the page to this component, showing how components contain each other.

A pagewill always return null. A component contained on a page returns its simple id. Other components return their container's id path followed by a period and their own name.

Specified by:

getIdPath in interface IComponent

See Also:

IComponent.getId()

getPage

public IPage getPage()

Description copied from interface: IComponent

Returns the page which ultimately contains the receiver. A page will return itself.

Specified by:

getPage in interface IComponent

setPage

public void setPage(IPage value)

Description copied from interface: IComponent

Sets the page which ultimiately contains the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.

Specified by:

setPage in interface IComponent

renderBody

public void renderBody(IMarkupWriter writer,
                       IRequestCycle cycle)

Renders all elements wrapped by the receiver.

Specified by:

renderBody in interface IComponent

setBinding

public void setBinding(java.lang.String name,
                       IBinding binding)

Adds the binding with the given name, replacing any existing binding with that name.

Specified by:

setBinding in interface IComponent

See Also:

getBinding(String)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getComponents

public java.util.Map getComponents()

Returns an unmodifiable Mapof components, keyed on component id. Never returns null, but may return an empty map. The returned map is immutable.

Specified by:

getComponents in interface IComponent

Returns:

A Map of components keyed on component id. May return an empty map, but won't return null.

getAssets

public java.util.Map getAssets()

Description copied from interface: IComponent

Returns the asset map for the component, which may be empty but will not be null.

The return value is unmodifiable.

Specified by:

getAssets in interface IComponent

getAsset

public IAsset getAsset(java.lang.String name)

Description copied from interface: IComponent

Returns the named asset, or null if not found.

Specified by:

getAsset in interface IComponent

getBindingNames

public java.util.Collection getBindingNames()

Description copied from interface: IComponent

Returns a Collectionof the names of all bindings (which includes bindings for both formal and informal parameters).

The return value is unmodifiable. It will be null for a page, or may simply be empty for a component with no bindings.

Specified by:

getBindingNames in interface IComponent

getBindings

public java.util.Map getBindings()

Returns an unmodifiable Mapof all bindings for this component.

Specified by:

getBindings in interface IComponent

Since:

1.0.5

getListeners

public ListenerMap getListeners()

Returns a ListenerMap for the component. A ListenerMap contains a number of synthetic read-only properties that implement the IActionListenerinterface, but in fact, cause public instance methods to be invoked.

Specified by:

getListeners in interface IComponent

Since:

1.0.2

getBeans

public IBeanProvider getBeans()

Returns the IBeanProviderfor this component. This is lazily created the first time it is needed.

Specified by:

getBeans in interface IComponent

Since:

1.0.4

finishLoad

protected void finishLoad()

Invoked, as a convienience, from finishLoad(IRequestCycle, IPageLoader, IComponentSpecification). This implemenation does nothing. Subclasses may override without invoking this implementation.

Since:

1.0.5

render

public final void render(IMarkupWriter writer,
                         IRequestCycle cycle)

The main method used to render the component. Invokes prepareForRender(IRequestCycle), then renderComponent(IMarkupWriter, IRequestCycle). cleanupAfterRender(IRequestCycle)is invoked in a finally block.

Subclasses should not override this method; instead they will implement renderComponent(IMarkupWriter, IRequestCycle).

Specified by:

render in interface IRender

Since:

2.0.3

prepareForRender

protected void prepareForRender(IRequestCycle cycle)

Invoked by render(IMarkupWriter, IRequestCycle)to prepare the component to render. This implementation sets JavaBeans properties from matching bound parameters. This implementation does nothing.

Since:

2.0.3

renderComponent

protected abstract void renderComponent(IMarkupWriter writer,
                                        IRequestCycle cycle)

Invoked by render(IMarkupWriter, IRequestCycle)to actually render the component (with any parameter values already set). This is the method that subclasses must implement.

Since:

2.0.3

cleanupAfterRender

protected void cleanupAfterRender(IRequestCycle cycle)

Invoked by render(IMarkupWriter, IRequestCycle)after the component renders. This implementation does nothing.

Since:

2.0.3

getNamespace

public INamespace getNamespace()

Description copied from interface: IComponent

Returns the INamespacein which the component was defined (as an alias).

Specified by:

getNamespace in interface IComponent

setNamespace

public void setNamespace(INamespace namespace)

Description copied from interface: IComponent

Sets the INamespacefor the component. The namespace should only be set once.

Specified by:

setNamespace in interface IComponent

getBody

public IRender[] getBody()

Returns the body of the component, the element (which may be static HTML or components) that the component immediately wraps. May return null. Do not modify the returned array. The array may be padded with nulls.

Since:

2.3

See Also:

getBodyCount()

getBodyCount

public int getBodyCount()

Returns the active number of elements in the the body, which may be zero.

Since:

2.3

See Also:

getBody()

pageEndRender

public void pageEndRender(PageEvent event)

Empty implementation of PageEndRenderListener.pageEndRender(PageEvent). This allows classes to implement PageRenderListenerand only implement the PageBeginRenderListener.pageBeginRender(PageEvent)method.

Since:

3.0

setProperty

public void setProperty(java.lang.String propertyName,
                        java.lang.Object value)

Deprecated.

Sets a property of a component.

Specified by:

setProperty in interface IComponent

Parameters:

propertyName - the property name

value - the provided value

Since:

3.0

See Also:

IComponent

getProperty

public java.lang.Object getProperty(java.lang.String propertyName)

Deprecated.

Gets a property of a component.

Specified by:

getProperty in interface IComponent

Parameters:

propertyName - the property name

Returns:

Object the value of property

Since:

3.0

See Also:

IComponent

isRendering

public final boolean isRendering()

Description copied from interface: IComponent

Returns true if the component is currently rendering.

Specified by:

isRendering in interface IComponent

Since:

4.0

isInActiveState

protected final boolean isInActiveState()

Returns true if the component has been transitioned into its active state by invoking enterActiveState()

Since:

4.0

enterActiveState

public final void enterActiveState()

Description copied from interface: IComponent

Invoked after IComponent.finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)to switch the component from its initial construction state into its active state. The difference concerns parameters, whose defaults values may be set from inside IComponent.finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).

Specified by:

enterActiveState in interface IComponent

Since:

4.0

checkActiveLock

protected final void checkActiveLock()

Since:

4.0

getMessages

public org.apache.hivemind.Messages getMessages()

Description copied from interface: IComponent

Returns component strings for the component. Starting in release 4.0, this method is unimplemented (and is automatically injected into each component implementation).

Specified by:

getMessages in interface IComponent

getSpecification

public IComponentSpecification getSpecification()

Description copied from interface: IComponent

Returns the specification which defines the component.

Specified by:

getSpecification in interface IComponent

getMessage

public java.lang.String getMessage(java.lang.String key)

Deprecated. To be removed in 4.1. Use getMessages() instead.

Returns a localized message.

Specified by:

getMessage in interface IComponent

Parameters:

key - the key used to locate the message

Returns:

the localized message for the key, or a placeholder if no message is defined for the key.

Since:

3.0

format

public java.lang.String format(java.lang.String key,
                               java.lang.Object[] arguments)

Deprecated. To be removed in 4.1. Use getMessages() instead.

Formats a localized message string, using Messages.format(java.lang.String, java.lang.Object[]).

Parameters:

key - the key used to obtain a localized pattern

arguments - passed to the formatter

Since:

3.0

format

public java.lang.String format(java.lang.String key,
                               java.lang.Object argument)

Deprecated. To be removed in 4.1. Use getMessages() instead.

Convienience method for invoking IMessages#format(String, Locale, Object)

Since:

3.0

format

public java.lang.String format(java.lang.String key,
                               java.lang.Object argument1,
                               java.lang.Object argument2)

Deprecated. To be removed in 4.1. Use getMessages() instead.

Convienience method for invoking Messages.format(String, Object, Object).

Since:

3.0

format

public java.lang.String format(java.lang.String key,
                               java.lang.Object argument1,
                               java.lang.Object argument2,
                               java.lang.Object argument3)

Deprecated. To be removed in 4.1. Use getMessages() instead.

Convienience method for Messages.format(String, Object, Object, Object).

Since:

3.0

getContainedComponent

public final IContainedComponent getContainedComponent()

Description copied from interface: IComponent

Returns the IContainedComponent. This will be null for pages. This property is set when a component is constructed, and links the component instance to the reference in the containing page or component's template or specification. This is useful to allow a component to know its type or the meta-data associated with the component.

Specified by:

getContainedComponent in interface IComponent

Returns:

the contained component, or null for a page.

Since:

4.0

setContainedComponent

public final void setContainedComponent(IContainedComponent containedComponent)

Description copied from interface: IComponent

Sets the IComponent.getContainedComponent() property; this may only be done once.

Specified by:

setContainedComponent in interface IComponent

Parameters:

containedComponent - may not be null

Since:

4.0