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, IDirectEvent, Component, IRender

Direct Known Subclasses:

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

public abstract class AbstractComponent
extends org.apache.hivemind.impl.BaseLocatable
implements IDirectEvent, Component

Abstract base class implementing the IComponentinterface.

Author:

Howard Lewis Ship

Field Summary

protected IRender[]	_body An aray of elements in the body of this component.
protected int	_bodyCount The number of IRenderobjects in the body of this component.

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	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.
boolean	equals(Object obj)
protected void	finishLoad() Invoked, as a convienience, from finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).
void	finishLoad(IRequestCycle cycle, IPageLoader loader, IComponentSpecification specification) Invokes finishLoad().
protected void	generateClientId()
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 IBeanProviderfor this component.
IBinding	getBinding(String name) Returns the named binding, or null if it doesn't exist.
Collection	getBindingNames() Returns a Collectionof the names of all bindings (which includes bindings for both formal and informal parameters).
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.
protected String	getBoundId()
abstract String	getClientId() Returns the component's client-side element id.
IComponent	getComponent(String id) Retrieves an contained component by its id.
Map	getComponents() Returns an unmodifiable Mapof components, keyed on component id.
IContainedComponent	getContainedComponent() Returns the IContainedComponent.
IRender[]	getContainedRenderers() Returns the list of of IRender elements contained by this component.
IComponent	getContainer() Returns the component which embeds the receiver.
IComponentEventInvoker	getEventInvoker() Returns the event connection manager services that handles creating/accepting browser events associated with various properties of components.
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.
IRender[]	getInnerRenderers() In some rare cases a component has both outer and inner renderers - such as with BaseComponent.
ListenerMap	getListeners() Returns a ListenerMap for the component.
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.
ComponentRenderWorker	getRenderWorker()
IComponentSpecification	getSpecification() Returns the specification which defines the component.
String	getSpecifiedId() Returns either the normal IComponent.getId() value OR the value of any binding named id - if one exists.
String	getTemplateTagName() Though most component implementations ignore the specific html tag used to reference a component, this value may be used for those components that do wish to use the same tag that was provided when rendering a component.
boolean	hasEvents() Checks if this component has been targeted / connected to for client side event listening via @EventListener.
int	hashCode()
protected boolean	isInActiveState() Returns true if the component has been transitioned into its active state by invoking enterActiveState().
boolean	isParameterBound(String parameterName) Returns true if the specified parameter is bound.
boolean	isRendering() Returns true if the component is currently rendering.
boolean	isStateful() Invoked by the event service to query the component as to whether it is stateful.
void	pageEndRender(PageEvent event) Empty implementation of PageEndRenderListener.pageEndRender(PageEvent).
String	peekClientId() Used internally to "peek" at what the next generated client id will be for this component when it renders.
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	renderIdAttribute(IMarkupWriter writer, IRequestCycle cycle) Renders the (unique) id attribute for this component.
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.
abstract void	setClientId(String id) Sets the client ID.
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	setHasEvents(boolean hasEvents) Sets whether or not this component has events.
void	setId(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	setTemplateTagName(String tag) Sets the template tag name used to reference this component.
String	toString()
void	triggerEvent(IRequestCycle cycle, BrowserEvent event) Invoked by the event service to have the component peform the appropriate action.

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

getLocation, setLocation

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.hivemind.LocationHolder

setLocation

Methods inherited from interface org.apache.hivemind.Locatable

getLocation

Field Detail

_bodyCount

protected int _bodyCount

The number of IRenderobjects in the body of this component.

_body

protected IRender[] _body

An aray of elements in the body of this component.

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

Parameters:

name - The lookup name the asset will be bound to and referenacable as.

asset - The asset to add.

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 doing all the necessary work of managing component state.

Specified by:

addComponent in interface IComponent

Parameters:

component - The component to add.

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

getContainedRenderers

public IRender[] getContainedRenderers()

Description copied from interface: Component

Returns the list of of IRender elements contained by this component. Ie whatever has been added via IComponent.addBody(IRender).

Specified by:

getContainedRenderers in interface Component

Returns:

The values, if any. Null otherwise.

getInnerRenderers

public IRender[] getInnerRenderers()

Description copied from interface: Component

In some rare cases a component has both outer and inner renderers - such as with BaseComponent. This value should return the normal inner renderers most components do in those instances while the other Component.getContainedRenderers() should return the outer renderers.

Specified by:

getInnerRenderers in interface Component

Returns:

The inner renderers if this component supports more than one type, null otherwise.

hasEvents

public boolean hasEvents()

Description copied from interface: Component

Checks if this component has been targeted / connected to for client side event listening via @EventListener.

Specified by:

hasEvents in interface Component

Returns:

True if anything has targeted this component, false otherwise.

setHasEvents

public void setHasEvents(boolean hasEvents)

Description copied from interface: Component

Sets whether or not this component has events.

Specified by:

setHasEvents in interface Component

Parameters:

hasEvents - Whether or not this component has connected events.

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.

renderIdAttribute

protected void renderIdAttribute(IMarkupWriter writer,
                                 IRequestCycle cycle)

Renders the (unique) id attribute for this component.

Parameters:

writer - The writer to render attribute in.

cycle - The current request.

getBinding

public IBinding getBinding(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(String parameterName)

Returns true if the specified parameter is bound.

Since:

4.0

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 override this method to simply return their page name.

Specified by:

getExtendedId in interface IComponent

See Also:

getIdPath()

getSpecifiedId

public String getSpecifiedId()

Description copied from interface: IComponent

Returns either the normal IComponent.getId() value OR the value of any binding named id - if one exists. Higher precedence is given to bound id values.

Specified by:

getSpecifiedId in interface IComponent

Returns:

The bound or normal component id, or null if neither exists.

Since:

4.1

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 pagewill 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 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()

getClientId

public abstract String getClientId()

Returns the component's client-side element id. This has traditionally been an IFormComponent only binding but now applies to all components. The method should check to see if any id parameter/property has been set already and use that above all others, falling back to IComponent.getId() if nothing else is found.

Specified by:

getClientId in interface IComponent

Returns:

the id, or null if the component doesn't support a client id.

Since:

4.1

setClientId

public abstract void setClientId(String id)

Description copied from interface: IComponent

Sets the client ID. It is strongly discouraged for you to try setting this unless you understand the ramifications of how the rest of the system relies on this functioning.

Specified by:

setClientId in interface IComponent

Parameters:

id - The client id to set.

peekClientId

public String peekClientId()

Used internally to "peek" at what the next generated client id will be for this component when it renders. Similar to the logic found in IRequestCycle.peekUniqueId(String).

Specified by:

peekClientId in interface IComponent

Returns:

The next possible client ID for this component.

generateClientId

protected void generateClientId()

getBoundId

protected String getBoundId()

getTemplateTagName

public String getTemplateTagName()

Description copied from interface: IComponent

Though most component implementations ignore the specific html tag used to reference a component, this value may be used for those components that do wish to use the same tag that was provided when rendering a component.

Example:

  <fieldset jwcid="@If" condition="true" >
      <input type="text" />
  </fieldset>
 

In the example above, the value of the template tag would be "fieldset" for the If component.

Specified by:

getTemplateTagName in interface IComponent

Returns:

The html element tag name originally specified when referencing the component.

setTemplateTagName

public void setTemplateTagName(String tag)

Sets the template tag name used to reference this component.

Set by the component template loader automatically, people shouldn't normally have any reason to try setting this.

Specified by:

setTemplateTagName in interface IComponent

Parameters:

tag - The tag name to set.

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(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 String toString()

Overrides:

toString in class Object

getComponents

public 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 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 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 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. The default implementation of this method is empty.

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.

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

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

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

getEventInvoker

public IComponentEventInvoker getEventInvoker()

Returns the event connection manager services that handles creating/accepting browser events associated with various properties of components.

Specified by:

getEventInvoker in interface IComponent

Returns:

eventInvoker, may not be null

triggerEvent

public void triggerEvent(IRequestCycle cycle,
                         BrowserEvent event)

Invoked by the event service to have the component peform the appropriate action.

Specified by:

triggerEvent in interface IDirectEvent

getRenderWorker

public ComponentRenderWorker getRenderWorker()

isStateful

public boolean isStateful()

Invoked by the event service to query the component as to whether it is stateful. If stateful and no HttpSession is active, then a StaleSessionException is thrown by the service.

Specified by:

isStateful in interface IDirectEvent

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object