org.apache.tapestry
Interface IComponent

All Superinterfaces:
IRender, org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder
All Known Subinterfaces:
IAction, IDirect, IExternalPage, IForm, IFormComponent, ILinkComponent, IPage, ITemplateComponent, TranslatedField, ValidatableField
All Known Implementing Classes:
AbstractComponent, AbstractFormComponent, AbstractLinkComponent, AbstractPage, AbstractPostfield, ActionLink, Any, BaseComponent, BasePage, Block, Body, Button, Card, Checkbox, Conditional, DatePicker, Deck, Delegator, Describe, DirectLink, Do, ElseBean, Exception, ExceptionDisplay, ExternalLink, FieldLabel, ForBean, Foreach, Form, Frame, GenericLink, Go, Hidden, IfBean, Image, Image, ImageSubmit, Input, Insert, InsertText, InvokeListener, LinkSubmit, ListEdit, OnEvent, Option, Option, PageLink, Postfield, PropertySelection, PropertySelection, Radio, RadioGroup, RenderBlock, RenderBody, RequestDisplay, Rollover, Script, Select, Select, SelectionField, ServiceLink, Setvar, Shell, StaleLink, Submit, TextArea, TextField, Timer, Upload, ValidField, WMLException, WMLStaleLink

public interface IComponent
extends IRender, org.apache.hivemind.LocationHolder

Defines an object which may be used to provide dynamic content on a Tapestry web page.

Components are created dynamically from thier class names (part of the IComponentSpecification).

Author:
Howard Leiws Ship

Method Summary
 void addAsset(java.lang.String name, IAsset asset)
          Adds an asset to the component.
 void addBody(IRender element)
          Adds a new renderable element to the receiver's body.
 void addComponent(IComponent component)
          Adds a component to a container.
 void enterActiveState()
          Invoked after finishLoad(IRequestCycle, IPageLoader, IComponentSpecification)to switch the component from its initial construction state into its active state.
 void finishLoad(IRequestCycle cycle, IPageLoader loader, IComponentSpecification specification)
          Allows a component to finish any setup after it has been constructed.
 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 a IBeanProvider from which managed beans can be obtained.
 IBinding getBinding(java.lang.String name)
          Returns the binding with the given name or null if not found.
 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 a Mapof the bindingsfor this component; this includes informal parameters as well as formal bindings.
 IComponent getComponent(java.lang.String id)
          Retrieves an contained component by its id.
 java.util.Map getComponents()
          Returns the contained components as an unmodifiable Map.
 IContainedComponent getContainedComponent()
          Returns the IContainedComponent.
 IComponent getContainer()
          Returns the component which embeds the receiver.
 java.lang.String getExtendedId()
          Returns a string identifying the name of the page and the id path of the reciever within the page (seperated by a slash).
 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 release 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. To be removed in 4.1. Use PropertyUtils.read(java.lang.Object, java.lang.String) instead
 IComponentSpecification getSpecification()
          Returns the specification which defines the component.
 boolean isRendering()
          Returns true if the component is currently rendering.
 void renderBody(IMarkupWriter writer, IRequestCycle cycle)
          Invoked to make the receiver render its body (the elements and components its tag wraps around, on its container's template).
 void setBinding(java.lang.String name, IBinding binding)
          Adds a binding to a container.
 void setContainedComponent(IContainedComponent containedComponent)
          Sets the 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. To be removed in 4.1. Use {@link org.apache.hivemind.util.PropertyUtils#read(java.lang.Object, java.lang.String) instead.
 
Methods inherited from interface org.apache.tapestry.IRender
render
 
Methods inherited from interface org.apache.hivemind.LocationHolder
setLocation
 
Methods inherited from interface org.apache.hivemind.Locatable
getLocation
 

Method Detail

addAsset

void addAsset(java.lang.String name,
              IAsset asset)
Adds an asset to the component. This is invoked from the page loader.


addComponent

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

See Also:
IPageLoader

addBody

void addBody(IRender element)
Adds a new renderable element to the receiver's body. The element may be either another component, or static HTML. Such elements come from inside the receiver's tag within its container's template, and represent static text and other components.

The method renderBody(IMarkupWriter, IRequestCycle)is used to render these elements.

Since:
2.2

getAssets

java.util.Map getAssets()
Returns the asset map for the component, which may be empty but will not be null.

The return value is unmodifiable.


getAsset

IAsset getAsset(java.lang.String name)
Returns the named asset, or null if not found.


getBinding

IBinding getBinding(java.lang.String name)
Returns the binding with the given name or null if not found.

Bindings are added to a component using setBinding(String,IBinding).


getBindingNames

java.util.Collection getBindingNames()
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.


getBindings

java.util.Map getBindings()
Returns a Mapof the bindingsfor this component; this includes informal parameters as well as formal bindings.

Since:
1.0.5

getComponent

IComponent getComponent(java.lang.String id)
Retrieves an contained component by its id. Contained components have unique ids within their container.

Throws:
ApplicationRuntimeException - runtime exception thrown if the named component does not exist.

getContainer

IComponent getContainer()
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.


setContainer

void setContainer(IComponent value)
Sets the container of the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.


getExtendedId

java.lang.String getExtendedId()
Returns a string identifying the name of the page and the id path of the reciever within the page (seperated by a slash). Note that this extended id is indetned primarily for identifying the component to the user (since slashes are legal characters within page names). Pages simply return their name.

See Also:
getIdPath()

getId

java.lang.String getId()
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.


setId

void setId(java.lang.String value)
Sets the id of the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.


getIdPath

java.lang.String getIdPath()
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.

See Also:
getId()

getPage

IPage getPage()
Returns the page which ultimately contains the receiver. A page will return itself.


setPage

void setPage(IPage value)
Sets the page which ultimiately contains the component. This is write-once, an attempt to change it later will throw an ApplicationRuntimeException.


getSpecification

IComponentSpecification getSpecification()
Returns the specification which defines the component.


renderBody

void renderBody(IMarkupWriter writer,
                IRequestCycle cycle)
Invoked to make the receiver render its body (the elements and components its tag wraps around, on its container's template). This method is public so that the RenderBodycomponent may operate.

Since:
2.2

setBinding

void setBinding(java.lang.String name,
                IBinding binding)
Adds a binding to a container. Should only be called during the page loading process (which is responsible for eror checking).

See Also:
IPageLoader

getComponents

java.util.Map getComponents()
Returns the contained components as an unmodifiable Map. This allows peer components to work together without directly involving their container ... the classic example is to have an Insertwork with an enclosing Foreach.

This is late addition to Tapestry, because it also opens the door to abuse, since it is quite possible to break the "black box" aspect of a component by interacting directly with components it embeds. This creates ugly interelationships between components that should be seperated.

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

finishLoad

void finishLoad(IRequestCycle cycle,
                IPageLoader loader,
                IComponentSpecification specification)
Allows a component to finish any setup after it has been constructed.

The exact timing is not specified, but any components contained by the receiving component will also have been constructed before this method is invoked.

As of release 1.0.6, this method is invoked before bindings are set. This should not affect anything, as bindings should only be used during renderring.

Release 2.2 added the cycle parameter which is, regretfully, not backwards compatible.

Since:
0.2.12

getMessages

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

Since:
3.0

getNamespace

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

Since:
2.2

setNamespace

void setNamespace(INamespace namespace)
Sets the INamespacefor the component. The namespace should only be set once.

Since:
2.2

setProperty

void setProperty(java.lang.String propertyName,
                 java.lang.Object value)
Deprecated. To be removed in 4.1. Use {@link org.apache.hivemind.util.PropertyUtils#read(java.lang.Object, java.lang.String) instead.

Sets a property of a component.

Parameters:
propertyName - the property name
value - the provided value

getProperty

java.lang.Object getProperty(java.lang.String propertyName)
Deprecated. To be removed in 4.1. Use PropertyUtils.read(java.lang.Object, java.lang.String) instead

Gets a property of a component.

Parameters:
propertyName - the property name
Returns:
Object the value of property

isRendering

boolean isRendering()
Returns true if the component is currently rendering.

Since:
4.0

enterActiveState

void enterActiveState()
Invoked after 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 finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).

Since:
4.0

getBeans

IBeanProvider getBeans()
Returns a IBeanProvider from which managed beans can be obtained.

Since:
4.0

getListeners

ListenerMap getListeners()
Returns a ListenerMap for the component. The map contains a number of synthetic read-only properties that implement the IActionListener interface, but in fact, cause public instance methods to be invoked (via reflection).

Since:
4.0

getMessage

java.lang.String getMessage(java.lang.String key)
Deprecated. To be removed in release 4.1. Use getMessages() instead.

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

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

getContainedComponent

IContainedComponent getContainedComponent()
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.

Returns:
the contained component, or null for a page.
Since:
4.0

setContainedComponent

void setContainedComponent(IContainedComponent containedComponent)
Sets the getContainedComponent() property; this may only be done once.

Parameters:
containedComponent - may not be null
Since:
4.0