com.primix.tapestry
Class AbstractComponent

java.lang.Object
  |
  +--com.primix.tapestry.AbstractComponent
All Implemented Interfaces:
IComponent, IRender
Direct Known Subclasses:
AbstractFormComponent, AbstractServiceLink, Any, BaseComponent, Block, Body, Conditional, Delegator, FieldLabel, Foreach, Form, Image, Insert, InsertBlock, InsertText, InsertWrapped, ListEdit, Option, Radio, Rollover, Script, Shell

public abstract class AbstractComponent
extends java.lang.Object
implements IComponent

Abstract base class implementing the IComponent interface.

Version:
$Id: AbstractComponent.java,v 1.26 2001/09/04 16:33:49 hship Exp $
Author:
Howard Ship

Field Summary
protected  java.lang.String id
          The simple id of this component.
protected  IPage page
          The page that contains the component, possibly itself (if the component is in fact, a page).
protected  ComponentSpecification specification
          The specification used to originally build the component.
protected  IRender[] wrapped
          An aray of elements wrapped by this component.
protected  int wrappedCount
          The number of IRender objects wrapped by this component.
 
Constructor Summary
AbstractComponent()
           
 
Method Summary
 void addAsset(java.lang.String name, IAsset asset)
          Adds an asset to the component.
 void addComponent(IComponent component)
          Adds a component to a container.
 void addWrapped(IRender element)
          Adds an element (which may be static text or a component) as a wrapped element of this component.
 void cleanupAfterRender(IRequestCycle cycle)
          Does nothing.
 void cleanupComponent()
          Does nothing.
protected  void finishLoad()
          Invoked from finishLoad(IPageLoader, ComponentSpecification) so that components can easily perform simple operations, such as registering for event notifications.
 void finishLoad(IPageLoader loader, ComponentSpecification specification)
          Invokes finishLoad().
protected  void fireObservedChange()
          Fires a change event for no single property; the receiver should note that the page containing the component is 'dirty' even if no property appears to have changed.
protected  void fireObservedChange(java.lang.String propertyName, boolean newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, byte newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, char newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, double newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, float newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, int newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, long newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, java.lang.Object newValue)
           
protected  void fireObservedChange(java.lang.String propertyName, short newValue)
           
protected  void generateAttributes(IResponseWriter writer, IRequestCycle cycle)
          Converts informal parameters into additional attributes on the curently open tag.
 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 null.
 IBeanProvider getBeans()
          Returns the IBeanProvider for 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 Collection of the names of all bindings (which includes bindings for both formal and informal parameters).
 java.util.Map getBindings()
          Returns a Map of all bindings for this component.
 ChangeObserver getChangeObserver()
          Return's the page's change observer.
 IComponent getComponent(java.lang.String id)
          Retrieves an contained component by its id.
 java.util.Map getComponents()
          Returns an unmodifiable Map of components, keyed on component id.
 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.
 IPage getPage()
          Returns the page which ultimately contains the receiver.
 ComponentSpecification getSpecification()
          Returns the specification which defines the component.
 void prepareForRender(IRequestCycle cycle)
          Does nothing.
 void renderWrapped(IResponseWriter writer, IRequestCycle cycle)
          Renders all elements wrapped by the receiver.
 void reset()
          Does nothing.
 void setBinding(java.lang.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(java.lang.String value)
          Sets the id of the component.
 void setPage(IPage value)
          Sets the page which ultimiately contains the component.
 void setSpecification(ComponentSpecification value)
          Sets the specification used by the component.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.primix.tapestry.IRender
render
 

Field Detail

specification

protected ComponentSpecification specification
The specification used to originally build the component.

page

protected IPage page
The page that contains the component, possibly itself (if the component is in fact, a page).

id

protected java.lang.String id
The simple id of this component.

wrappedCount

protected int wrappedCount
The number of IRender objects wrapped by this component.

wrapped

protected IRender[] wrapped
An aray of elements wrapped by this component.
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
Following copied from interface: com.primix.tapestry.IComponent
See Also:
IPageLoader

addWrapped

public void addWrapped(IRender element)
Adds an element (which may be static text or a component) as a wrapped element of this component. Such elements are rendered by renderWrapped(IResponseWriter, IRequestCycle).
Specified by:
addWrapped in interface IComponent

finishLoad

public void finishLoad(IPageLoader loader,
                       ComponentSpecification specification)
                throws PageLoaderException
Invokes finishLoad(). Subclasses may overide as needed, but must invoke this implementation (or finishLoad(). BaseComponent loads its HTML template.
Specified by:
finishLoad in interface IComponent

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  int newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  java.lang.Object newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  boolean newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  double newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  float newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  long newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  char newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  byte newValue)

fireObservedChange

protected void fireObservedChange(java.lang.String propertyName,
                                  short newValue)

fireObservedChange

protected void fireObservedChange()
Fires a change event for no single property; the receiver should note that the page containing the component is 'dirty' even if no property appears to have changed. This is useful in situations when a property is a mutable object (such as a Collection) and the state of the property value is changing, even though the property is not.

generateAttributes

protected void generateAttributes(IResponseWriter 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, IResponseWriter.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.

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()
Return's the page's change observer. In practical terms, this will be an IPageRecorder.
See Also:
IPage.getChangeObserver()

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
Following copied from interface: com.primix.tapestry.IComponent
Throws:
NoSuchComponentException - runtime exception thrown if the named component does not exist.

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 simply return their 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 page will 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 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
Following copied from interface: com.primix.tapestry.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 ComponentSpecification getSpecification()
Description copied from interface: IComponent
Returns the specification which defines the component.
Specified by:
getSpecification in interface IComponent

setSpecification

public void setSpecification(ComponentSpecification 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

renderWrapped

public void renderWrapped(IResponseWriter writer,
                          IRequestCycle cycle)
                   throws RequestCycleException
Renders all elements wrapped by the receiver.
Specified by:
renderWrapped 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.

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 @link #generateAttribute(IResponseWriter, String[]) is to be used. It relies on using the collection of bindings (to store informal parameters).

Specified by:
setBinding in interface IComponent
Following copied from interface: com.primix.tapestry.IComponent
See Also:
IPageLoader

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getComponents

public java.util.Map getComponents()
Returns an unmodifiable Map of components, keyed on component id.
Specified by:
getComponents in interface IComponent

getAssets

public java.util.Map getAssets()
Description copied from interface: IComponent
Returns the asset map for the component, which may 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 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 java.util.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 and/or IDirectListener interfaces, 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 from finishLoad(IPageLoader, ComponentSpecification) so that components can easily perform simple operations, such as registering for event notifications. This is a convienience, providing a much simpler method signature to override.

This implementation checks to see if the component implements ILifecycle, if so, the component sets up listeners to invoke the implementations of the ILifecycle methods. This support will be removed in release 1.1.

Since:
1.0.5

cleanupAfterRender

public void cleanupAfterRender(IRequestCycle cycle)
Does nothing. To be removed in release 1.1.
See Also:
finishLoad(), ILifecycle

prepareForRender

public void prepareForRender(IRequestCycle cycle)
Does nothing. To be removed in release 1.1.
See Also:
finishLoad(), ILifecycle

reset

public void reset()
Does nothing. To be removed in release 1.1.
See Also:
finishLoad(), ILifecycle

cleanupComponent

public void cleanupComponent()
Does nothing. To be removed in release 1.1.
See Also:
finishLoad(), ILifecycle