org.apache.tapestry
Class AbstractComponent

java.lang.Object
  extended by org.apache.hivemind.impl.BaseLocatable
      extended by 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