org.apache.tapestry
Class AbstractComponent

java.lang.Object
  org.apache.tapestry.spec.BaseLocatable
      org.apache.tapestry.AbstractComponent

All Implemented Interfaces:

IComponent, ILocatable, ILocationHolder, IRender

Direct Known Subclasses:

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

public abstract class AbstractComponent
extends BaseLocatable
implements IComponent

Abstract base class implementing the IComponent interface.

Version:

$Id: AbstractComponent.java 243791 2004-02-19 17:38:13Z hlship $

Author:

Howard Lewis Ship

Constructor Summary

AbstractComponent()

Method Summary

void	addAsset(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	cleanupAfterRender(IRequestCycle cycle) Invoked by render(IMarkupWriter, IRequestCycle) after the component renders, to clear any parameters back to null (or 0, or false, or whatever the correct default is).
protected void	finishLoad() Invoked, as a convienience, from finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).
void	finishLoad(IRequestCycle cycle, IPageLoader loader, IComponentSpecification specification) Registers this component as a listener of the page if it implements PageDetachListener or PageRenderListener.
protected void	fireObservedChange(String propertyName, boolean newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, boolean) instead.
protected void	fireObservedChange(String propertyName, byte newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, byte) instead.
protected void	fireObservedChange(String propertyName, char newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, char) instead.
protected void	fireObservedChange(String propertyName, double newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, double) instead.
protected void	fireObservedChange(String propertyName, float newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, float) instead.
protected void	fireObservedChange(String propertyName, int newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, int) instead.
protected void	fireObservedChange(String propertyName, long newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, long) instead.
protected void	fireObservedChange(String propertyName, Object newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, Object) instead.
protected void	fireObservedChange(String propertyName, short newValue) Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, short) instead.
String	format(String key, Object argument) Convienience method for invoking IMessages.format(String, Object)
String	format(String key, Object[] arguments) Formats a localized message string, using IMessages.format(java.lang.String, java.lang.Object[]).
String	format(String key, Object argument1, Object argument2) Convienience method for invoking IMessages.format(String, Object, Object).
String	format(String key, Object argument1, Object argument2, Object argument3) Convienience method for IMessages.format(String, Object, Object, Object).
String	formatString(String key, Object argument) Deprecated. To be removed in 3.1. Use format(String, Object) instead.
String	formatString(String key, Object[] arguments) Deprecated. To be removed in 3.1. Use format(String, Object[]) instead.
String	formatString(String key, Object argument1, Object argument2) Deprecated. To be removed in 3.1. Use format(String, Object, Object) instead.
String	formatString(String key, Object argument1, Object argument2, Object argument3) Deprecated. To be removed in 3.1. Use format(String, Object, Object, Object) instead.
protected void	generateAttributes(IMarkupWriter writer, IRequestCycle cycle) Deprecated. To be removed in 3.1. Use renderInformalParameters(IMarkupWriter, IRequestCycle) instead.
IAsset	getAsset(String name) Returns the named asset, or null if not found.
Map	getAssets() Returns the asset map for the component, which may be empty but will not be null.
IBeanProvider	getBeans() Returns the IBeanProvider for this component.
IBinding	getBinding(String name) Returns the named binding, or null if it doesn't exist.
Collection	getBindingNames() Returns a Collection of the names of all bindings (which includes bindings for both formal and informal parameters).
Map	getBindings() Returns a Map of 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.
ChangeObserver	getChangeObserver() Deprecated. To be removed in 3.1; use IPage.getChangeObserver().
IComponent	getComponent(String id) Retrieves an contained component by its id.
Map	getComponents() Returns an unmodifiable Map of components, keyed on component id.
IComponent	getContainer() Returns the component which embeds the receiver.
String	getExtendedId() Returns the name of the page, a slash, and this component's id path.
String	getId() Returns the simple id of the component, as defined in its specification.
String	getIdPath() Returns the qualified id of the component.
ListenerMap	getListeners() Returns a ListenerMap for the component.
String	getMessage(String key) Returns a localized string message.
IMessages	getMessages() Returns component strings for the component.
INamespace	getNamespace() Returns the INamespace in which the component was defined (as an alias).
IPage	getPage() Returns the page which ultimately contains the receiver.
Object	getProperty(String propertyName) Gets a property of a component.
IComponentSpecification	getSpecification() Returns the specification which defines the component.
String	getString(String key) Obtains the IMessages for this component (if necessary), and gets the string from it.
void	pageEndRender(PageEvent event) Empty implementation of PageRenderListener.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(String name, IBinding binding) Adds the binding with the given name, replacing any existing binding with that name.
void	setContainer(IComponent value) Sets the container of the component.
void	setId(String value) Sets the id of the component.
void	setNamespace(INamespace namespace) Sets the INamespace for the component.
void	setPage(IPage value) Sets the page which ultimiately contains the component.
void	setProperty(String propertyName, Object value) Sets a property of a component.
void	setSpecification(IComponentSpecification value) Sets the specification used by the component.
String	toString()

Methods inherited from class org.apache.tapestry.spec.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.tapestry.ILocationHolder

setLocation

Methods inherited from interface org.apache.tapestry.ILocatable

getLocation

Constructor Detail

AbstractComponent

public AbstractComponent()

Method Detail

addAsset

public void addAsset(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)

Registers this component as a listener of the page if it implements PageDetachListener or PageRenderListener.

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

Specified by:

finishLoad in interface IComponent

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  int newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, int) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  Object newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, Object) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  boolean newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, boolean) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  double newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, double) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  float newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, float) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  long newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, long) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  char newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, char) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  byte newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, byte) instead.

fireObservedChange

protected void fireObservedChange(String propertyName,
                                  short newValue)

Deprecated. To be removed in 3.1. Use Tapestry.fireObservedChange(IComponent, String, short) instead.

generateAttributes

protected void generateAttributes(IMarkupWriter writer,
                                  IRequestCycle cycle)

Deprecated. To be removed in 3.1. Use renderInformalParameters(IMarkupWriter, IRequestCycle) instead.

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 IComponent and a HTML element.

Iterates through the bindings for this component. Filters out bindings when the name matches a formal parameter (as of 1.0.5, informal bindings are weeded out at page load / template load time, if they match a formal parameter, or a specificied reserved name). For the most part, all the bindings here are either informal parameter, or formal parameter without a corresponding JavaBeans property.

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(IRequestCycle) 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(String name)

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

This method looks for a JavaBeans property with an appropriate name, of type IBinding. The property should be named nameBinding. If it exists and is both readable and writable, then it is accessor method is invoked. Components which implement such methods can access their own binding through their instance variables instead of invoking this method, a performance optimization.

Specified by:

getBinding in interface IComponent

See Also:

setBinding(String,IBinding)

getChangeObserver

public ChangeObserver getChangeObserver()

Deprecated. To be removed in 3.1; use IPage.getChangeObserver().

Return's the page's change observer. In practical terms, this will be an IPageRecorder.

See Also:

IPage.getChangeObserver()

getComponent

public IComponent getComponent(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 String getExtendedId()

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

Specified by:

getExtendedId in interface IComponent

See Also:

getIdPath()

getId

public 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 page will always return null.

Specified by:

getId in interface IComponent

setId

public void setId(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 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 page will 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

getSpecification

public IComponentSpecification getSpecification()

Description copied from interface: IComponent

Returns the specification which defines the component.

Specified by:

getSpecification in interface IComponent

setSpecification

public void setSpecification(IComponentSpecification value)

Description copied from interface: IComponent

Sets the specification used by the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.

Specified by:

setSpecification 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(String name,
                       IBinding binding)

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

This method checks to see if a matching JavaBeans property (with a name of nameBinding and a type of IBinding) exists. If so, that property is updated. An optimized component can simply implement accessor and mutator methods and then access its bindings via its own instance variables, rather than going through getBinding(String).

Informal parameters should not be stored in instance variables if renderInformalParameters(IMarkupWriter, IRequestCycle) is to be used. It relies on using the collection of bindings (to store informal parameters).

Specified by:

setBinding in interface IComponent

See Also:

IPageLoader

toString

public String toString()

Overrides:

toString in class Object

getComponents

public Map getComponents()

Returns an unmodifiable Map of 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 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(String name)

Description copied from interface: IComponent

Returns the named asset, or null if not found.

Specified by:

getAsset in interface IComponent

getBindingNames

public Collection getBindingNames()

Description copied from interface: IComponent

Returns a Collection of 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 Map getBindings()

Returns a Map of all bindings for this component. This implementation is expensive, since it has to merge the disassociated bindings (informal parameters, and parameters without a JavaBeans property) with the associated bindings (formal parameters with a JavaBeans property).

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 IActionListener interface, but in fact, cause public instance methods to be invoked.

Since:

1.0.2

getBeans

public IBeanProvider getBeans()

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

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. Subclasses that override this method must invoke this implementation as well.

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, to clear any parameters back to null (or 0, or false, or whatever the correct default is). Primarily, this is used to ensure that the component doesn't hold onto any objects that could otherwise be garbage collected.

Subclasses may override this implementation, but must also invoke it.

Since:

2.0.3

getMessages

public IMessages getMessages()

Description copied from interface: IComponent

Returns component strings for the component.

Specified by:

getMessages in interface IComponent

Since:

3.0

getString

public String getString(String key)

Obtains the IMessages for this component (if necessary), and gets the string from it.

Specified by:

getString 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.

getMessage

public String getMessage(String key)

Description copied from interface: IComponent

Returns a localized string message. Each component has an optional set of localized message strings that are read from properties files.

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.

formatString

public String formatString(String key,
                           Object[] arguments)

Deprecated. To be removed in 3.1. Use format(String, Object[]) instead.

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

Parameters:

key - the key used to obtain a localized pattern using getString(String)

arguments - passed to the formatter

Since:

2.2

format

public String format(String key,
                     Object[] arguments)

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

Parameters:

key - the key used to obtain a localized pattern using getString(String)

arguments - passed to the formatter

Since:

3.0

formatString

public String formatString(String key,
                           Object argument)

Deprecated. To be removed in 3.1. Use format(String, Object) instead.

Convienience method for invoking IMessages.format(String, Object[])

Since:

2.2

format

public String format(String key,
                     Object argument)

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

Since:

3.0

formatString

public String formatString(String key,
                           Object argument1,
                           Object argument2)

Deprecated. To be removed in 3.1. Use format(String, Object, Object) instead.

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

Since:

2.2

format

public String format(String key,
                     Object argument1,
                     Object argument2)

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

Since:

3.0

formatString

public String formatString(String key,
                           Object argument1,
                           Object argument2,
                           Object argument3)

Deprecated. To be removed in 3.1. Use format(String, Object, Object, Object) instead.

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

Since:

2.2

format

public String format(String key,
                     Object argument1,
                     Object argument2,
                     Object argument3)

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

Since:

3.0

getNamespace

public INamespace getNamespace()

Description copied from interface: IComponent

Returns the INamespace in 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 INamespace for 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 PageRenderListener.pageEndRender(PageEvent). This allows classes to implement PageRenderListener and only implement the PageRenderListener.pageBeginRender(PageEvent) method.

Since:

3.0

setProperty

public void setProperty(String propertyName,
                        Object value)

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 Object getProperty(String propertyName)

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