org.apache.tapestry.spec
Class ComponentSpecification

java.lang.Object
  org.apache.tapestry.util.BasePropertyHolder
      org.apache.tapestry.spec.LocatablePropertyHolder
          org.apache.tapestry.spec.ComponentSpecification

All Implemented Interfaces:

org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder, IComponentSpecification, IEventListener, IPropertyHolder

public class ComponentSpecification
extends LocatablePropertyHolder
implements IComponentSpecification

A specification for a component, as read from an XML specification file.

A specification consists of

• An implementing class
• An optional description
• A set of contained components
• Bindings for the properties of each contained component
• A set of named assets
• Definitions for managed beans
• Any reserved names (used for HTML attributes)
• Declared properties
• Property injections

From this information, an actual component may be instantiated and initialized. Instantiating a component is usually a recursive process, since to initialize a container component, it is necessary to instantiate and initialize its contained components as well.

Author:

Howard Lewis Ship

See Also:

IComponent, IContainedComponent, IPageLoader

Field Summary

protected Map	_assets Keyed on asset name, value is IAssetSpecification.
protected Map	_beans Defines all helper beans.
protected Map	_components Keyed on component id, value is IContainedComponent.
protected Map	_parameters Defines all formal parameters.
protected Set	_reservedParameterNames The names of all reserved informal parameter names (as lower-case).

Constructor Summary

ComponentSpecification()

Method Summary

void	addAsset(String name, IAssetSpecification asset)
void	addBeanSpecification(String name, IBeanSpecification specification)
void	addComponent(String id, IContainedComponent component)
void	addElementEventListener(String elementId, String[] events, String methodName, String formId, boolean validateForm, boolean async, boolean focus) Adds a deferred event listener binding for the specified html element.
void	addEventListener(String componentId, String[] events, String methodName, String formId, boolean validateForm, boolean async, boolean focus, boolean autoSubmit) Adds a deferred event listener binding for the specified component.
void	addInjectSpecification(InjectSpecification spec) Adds a InjectSpecification.
void	addParameter(IParameterSpecification spec) Adds the parameter.
void	addPropertySpecification(IPropertySpecification spec) Adds a new property specification.
void	addReservedParameterName(String value) Adds the value as a reserved name.
void	connectAutoSubmitEvents(IComponent component, IForm form) Invoked during rendering when a component has been detected as a IFormComponent and may possibly need its events to be wired up as form events.
boolean	equals(Object obj)
boolean	getAllowBody() Returns true if the component is allowed to wrap other elements (static HTML or other components).
boolean	getAllowInformalParameters() Returns true if the component allows informal parameters (parameters not formally defined).
IAssetSpecification	getAsset(String name) Returns the IAssetSpecificationwith the given name, or null if no such specification exists.
List	getAssetNames() Returns a List of the String names of all assets, in alphabetical order.
Collection	getBeanNames() Returns an unmodifiable collection of the names of all beans.
IBeanSpecification	getBeanSpecification(String name) Returns the IBeanSpecificationfor the given name, or null if not such specification exists.
IContainedComponent	getComponent(String id) Returns the specification of a contained component with the given id, or null if no such contained component exists.
String	getComponentClassName() Returns the class name to be used when instantiating the component, or null if no class name was provided in the specification (in which case, a system of defaults will be used to determine the class name).
Map	getComponentEvents() Gets all component event mappings.
ComponentEventProperty	getComponentEvents(String id) Gets component bound event properties.
List	getComponentIds() Returns an List of the String names of the IContainedComponents for this component.
String	getDescription() Returns the documentation for this component.
Map	getElementEvents() Gets all mapped element events for this component.
ComponentEventProperty	getElementEvents(String id) Gets element bound event properties.
EventBoundListener[]	getFormEvents(String formId, BrowserEvent event) Returns a list of element / component bound event listeners that were specified as invoking the form component with a matching id to formId of type EventBoundListener .
List	getInjectSpecifications() Returns the list of InjectSpecification.
IParameterSpecification	getParameter(String name) Returns the specification of a parameter with the given name, or null if no such parameter exists.
List	getParameterNames() Returns a List of of String names of all parameters.
IPropertySpecification	getPropertySpecification(String name) Returns the named IPropertySpecification, or null if no such specification exist.
List	getPropertySpecificationNames() Returns a sorted, immutable list of the names of all IPropertySpecifications.
String	getPublicId() Returns the XML Public Id for the specification file, or null if not applicable.
Collection	getRequiredParameters() Returns an unordered collection of IParameterSpecification, for all parameters that are required.
Set	getReservedParameterNames() Returns a Set of Strings; the reserved parameter names for the component.
org.apache.hivemind.Resource	getSpecificationLocation()
boolean	hasElementEvents() Checks if any element events are bound to this component.
int	hashCode()
boolean	isDeprecated() Returns true if the component is deprecated.
boolean	isPageSpecification() Returns true if the specification is known to be a page specification and not a component specification.
boolean	isReservedParameterName(String value) Returns true if the value specified is in the reserved name list.
void	rewireComponentId(String componentId, String extendedId, String idPath) Invoked during page load to map event connections previously made via the IComponent.getId() identifier to use the more unique IComponent.getIdPath().
void	setAllowBody(boolean value)
void	setAllowInformalParameters(boolean value)
void	setComponentClassName(String value)
void	setDeprecated(boolean deprecated)
void	setDescription(String description) Sets the documentation for this component.
void	setPageSpecification(boolean pageSpecification)
void	setPublicId(String publicId)
void	setSpecificationLocation(org.apache.hivemind.Resource specificationLocation)
String	toString()

Methods inherited from class org.apache.tapestry.spec.LocatablePropertyHolder

getLocation, setLocation

Methods inherited from class org.apache.tapestry.util.BasePropertyHolder

getProperty, getPropertyNames, removeProperty, setProperty

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.tapestry.util.IPropertyHolder

getProperty, getPropertyNames, removeProperty, setProperty

Methods inherited from interface org.apache.hivemind.LocationHolder

setLocation

Methods inherited from interface org.apache.hivemind.Locatable

getLocation

Field Detail

_components

protected Map _components

Keyed on component id, value is IContainedComponent.

_assets

protected Map _assets

Keyed on asset name, value is IAssetSpecification.

_parameters

protected Map _parameters

Defines all formal parameters. Keyed on parameter name, value is IParameterSpecification.

_beans

protected Map _beans

Defines all helper beans. Keyed on name, value is IBeanSpecification.

Since:

1.0.4

_reservedParameterNames

protected Set _reservedParameterNames

The names of all reserved informal parameter names (as lower-case). This allows the page loader to filter out any informal parameters during page load, rather than during render.

Since:

1.0.5

Constructor Detail

ComponentSpecification

public ComponentSpecification()

Method Detail

addAsset

public void addAsset(String name,
                     IAssetSpecification asset)

Specified by:

addAsset in interface IComponentSpecification

Throws:

org.apache.hivemind.ApplicationRuntimeException - if the name already exists.

addComponent

public void addComponent(String id,
                         IContainedComponent component)

Specified by:

addComponent in interface IComponentSpecification

Throws:

org.apache.hivemind.ApplicationRuntimeException - if the id is already defined.

addParameter

public void addParameter(IParameterSpecification spec)

Adds the parameter. The name is added as a reserved name.

Specified by:

addParameter in interface IComponentSpecification

Throws:

org.apache.hivemind.ApplicationRuntimeException - if the name already exists.

getAllowBody

public boolean getAllowBody()

Returns true if the component is allowed to wrap other elements (static HTML or other components). The default is true.

Specified by:

getAllowBody in interface IComponentSpecification

See Also:

setAllowBody(boolean)

getAllowInformalParameters

public boolean getAllowInformalParameters()

Returns true if the component allows informal parameters (parameters not formally defined). Informal parameters are generally used to create additional HTML attributes for an HTML tag rendered by the component. This is often used to specify JavaScript event handlers or the class of the component (for Cascarding Style Sheets).

The default value is true.

Specified by:

getAllowInformalParameters in interface IComponentSpecification

See Also:

setAllowInformalParameters(boolean)

getAsset

public IAssetSpecification getAsset(String name)

Returns the IAssetSpecificationwith the given name, or null if no such specification exists.

Specified by:

getAsset in interface IComponentSpecification

See Also:

addAsset(String,IAssetSpecification)

getAssetNames

public List getAssetNames()

Returns a List of the String names of all assets, in alphabetical order.

Specified by:

getAssetNames in interface IComponentSpecification

getComponent

public IContainedComponent getComponent(String id)

Returns the specification of a contained component with the given id, or null if no such contained component exists.

Specified by:

getComponent in interface IComponentSpecification

See Also:

addComponent(String, IContainedComponent)

getComponentClassName

public String getComponentClassName()

Description copied from interface: IComponentSpecification

Returns the class name to be used when instantiating the component, or null if no class name was provided in the specification (in which case, a system of defaults will be used to determine the class name).

Specified by:

getComponentClassName in interface IComponentSpecification

getComponentIds

public List getComponentIds()

Returns an List of the String names of the IContainedComponents for this component.

Specified by:

getComponentIds in interface IComponentSpecification

See Also:

addComponent(String, IContainedComponent)

getParameter

public IParameterSpecification getParameter(String name)

Returns the specification of a parameter with the given name, or null if no such parameter exists.

Specified by:

getParameter in interface IComponentSpecification

See Also:

addParameterByName(String, IParameterSpecification)

getRequiredParameters

public Collection getRequiredParameters()

Description copied from interface: IComponentSpecification

Returns an unordered collection of IParameterSpecification, for all parameters that are required. This includes only "real" parameters, not aliases.

Specified by:

getRequiredParameters in interface IComponentSpecification

getParameterNames

public List getParameterNames()

Returns a List of of String names of all parameters. This list is in alphabetical order.

Specified by:

getParameterNames in interface IComponentSpecification

See Also:

addParameterByName(String, IParameterSpecification)

setAllowBody

public void setAllowBody(boolean value)

Specified by:

setAllowBody in interface IComponentSpecification

setAllowInformalParameters

public void setAllowInformalParameters(boolean value)

Specified by:

setAllowInformalParameters in interface IComponentSpecification

setComponentClassName

public void setComponentClassName(String value)

Specified by:

setComponentClassName in interface IComponentSpecification

addBeanSpecification

public void addBeanSpecification(String name,
                                 IBeanSpecification specification)

Specified by:

addBeanSpecification in interface IComponentSpecification

Throws:

org.apache.hivemind.ApplicationRuntimeException - if the bean already has a specification.

Since:

1.0.4

getBeanSpecification

public IBeanSpecification getBeanSpecification(String name)

Returns the IBeanSpecificationfor the given name, or null if not such specification exists.

Specified by:

getBeanSpecification in interface IComponentSpecification

Since:

1.0.4

getBeanNames

public Collection getBeanNames()

Returns an unmodifiable collection of the names of all beans.

Specified by:

getBeanNames in interface IComponentSpecification

addReservedParameterName

public void addReservedParameterName(String value)

Adds the value as a reserved name. Reserved names are not allowed as the names of informal parameters. Since the comparison is caseless, the value is converted to lowercase before being stored.

Specified by:

addReservedParameterName in interface IComponentSpecification

Since:

1.0.5

isReservedParameterName

public boolean isReservedParameterName(String value)

Returns true if the value specified is in the reserved name list. The comparison is caseless. All formal parameters are automatically in the reserved name list, as well as any additional reserved names specified in the component specification. The latter refer to HTML attributes generated directly by the component.

Specified by:

isReservedParameterName in interface IComponentSpecification

Since:

1.0.5

toString

public String toString()

Overrides:

toString in class Object

getDescription

public String getDescription()

Returns the documentation for this component.

Specified by:

getDescription in interface IComponentSpecification

Since:

1.0.9

setDescription

public void setDescription(String description)

Sets the documentation for this component.

Specified by:

setDescription in interface IComponentSpecification

Since:

1.0.9

getPublicId

public String getPublicId()

Returns the XML Public Id for the specification file, or null if not applicable.

This method exists as a convienience for the Spindle plugin. A previous method used an arbitrary version string, the public id is more useful and less ambiguous.

Specified by:

getPublicId in interface IComponentSpecification

Since:

2.2

setPublicId

public void setPublicId(String publicId)

Specified by:

setPublicId in interface IComponentSpecification

Since:

2.2 *

isPageSpecification

public boolean isPageSpecification()

Returns true if the specification is known to be a page specification and not a component specification. Earlier versions of the framework did not distinguish between the two, but starting in 2.2, there are seperate XML entities for pages and components. Pages omit several attributes and entities related to parameters, as parameters only make sense for components.

Specified by:

isPageSpecification in interface IComponentSpecification

Since:

2.2

setPageSpecification

public void setPageSpecification(boolean pageSpecification)

Specified by:

setPageSpecification in interface IComponentSpecification

Since:

2.2 *

getSpecificationLocation

public org.apache.hivemind.Resource getSpecificationLocation()

Specified by:

getSpecificationLocation in interface IComponentSpecification

Since:

3.0 *

setSpecificationLocation

public void setSpecificationLocation(org.apache.hivemind.Resource specificationLocation)

Specified by:

setSpecificationLocation in interface IComponentSpecification

Since:

3.0 *

addPropertySpecification

public void addPropertySpecification(IPropertySpecification spec)

Adds a new property specification. The name of the property must not already be defined (and must not change after being added).

Specified by:

addPropertySpecification in interface IComponentSpecification

Since:

3.0

getPropertySpecificationNames

public List getPropertySpecificationNames()

Returns a sorted, immutable list of the names of all IPropertySpecifications.

Specified by:

getPropertySpecificationNames in interface IComponentSpecification

Since:

3.0

getPropertySpecification

public IPropertySpecification getPropertySpecification(String name)

Returns the named IPropertySpecification, or null if no such specification exist.

Specified by:

getPropertySpecification in interface IComponentSpecification

Since:

3.0

See Also:

addPropertySpecification(IPropertySpecification)

addInjectSpecification

public void addInjectSpecification(InjectSpecification spec)

Description copied from interface: IComponentSpecification

Adds a InjectSpecification.

Specified by:

addInjectSpecification in interface IComponentSpecification

getInjectSpecifications

public List getInjectSpecifications()

Description copied from interface: IComponentSpecification

Returns the list of InjectSpecification. Will return an empty list if no specifications have been added.

Specified by:

getInjectSpecifications in interface IComponentSpecification

isDeprecated

public boolean isDeprecated()

Description copied from interface: IComponentSpecification

Returns true if the component is deprecated. Deprecated components generate a warning when used.

Specified by:

isDeprecated in interface IComponentSpecification

Since:

4.0

setDeprecated

public void setDeprecated(boolean deprecated)

Specified by:

setDeprecated in interface IComponentSpecification

Since:

4.0

getReservedParameterNames

public Set getReservedParameterNames()

Description copied from interface: IComponentSpecification

Returns a Set of Strings; the reserved parameter names for the component. This combines explicit reserved names with formal parameter names. Each parameter name in the Set will be all lower case (to facilitate a caseless comparison).

Specified by:

getReservedParameterNames in interface IComponentSpecification

addEventListener

public void addEventListener(String componentId,
                             String[] events,
                             String methodName,
                             String formId,
                             boolean validateForm,
                             boolean async,
                             boolean focus,
                             boolean autoSubmit)

Adds a deferred event listener binding for the specified component.

Specified by:

addEventListener in interface IEventListener

Parameters:

componentId - The component this is for.

events - The events that should cause the listener to be executed.

methodName - The page/component listener name that should be executed when one of the supplied events occurs.

formId - The optional id of the form that should be submitted as part of this event invocation.

validateForm - If a formId was specified, whether or not that form should have client side valiation invoked during the process.

async - If submitting a form, whether or not to do it asynchronously.

focus - If submitting a form, controls whether or not to focus it after an update.

autoSubmit - If true - auto form wiring is performed on any component targets implementing IFormComponent so that the enclosing form is submitted as part of the event in order to maintain consistent form state as in normal listener method invocations.

addElementEventListener

public void addElementEventListener(String elementId,
                                    String[] events,
                                    String methodName,
                                    String formId,
                                    boolean validateForm,
                                    boolean async,
                                    boolean focus)

Adds a deferred event listener binding for the specified html element.

Specified by:

addElementEventListener in interface IEventListener

Parameters:

elementId - The client side html element id to match against.

events - The client side events to bind to.

methodName - The listener that should be invoked when the event happens.

formId - The optional id of the form that should be submitted as part of this event invocation.

validateForm - If a formId was specified, whether or not that form should have client side valiation invoked during the process.

async - If submitting a form, whether or not to do it asynchronously.

focus - If submitting a form, controls whether or not to focus it after an update.

connectAutoSubmitEvents

public void connectAutoSubmitEvents(IComponent component,
                                    IForm form)

Description copied from interface: IEventListener

Invoked during rendering when a component has been detected as a IFormComponent and may possibly need its events to be wired up as form events.

Specified by:

connectAutoSubmitEvents in interface IEventListener

Parameters:

component - The component to rewire form events for.

form - The form containing the component.

rewireComponentId

public void rewireComponentId(String componentId,
                              String extendedId,
                              String idPath)

Description copied from interface: IEventListener

Invoked during page load to map event connections previously made via the IComponent.getId() identifier to use the more unique IComponent.getIdPath().

Specified by:

rewireComponentId in interface IEventListener

Parameters:

componentId - The base component id.

extendedId - The id of the component as returned by IComponent.getExtendedId()

idPath - The id of the component as returned by IComponent.getIdPath()

getComponentEvents

public ComponentEventProperty getComponentEvents(String id)

Gets component bound event properties.

Specified by:

getComponentEvents in interface IEventListener

Parameters:

id - The component to get event listeners for.

Returns:

The bound component event property container, or null if none exist.

getComponentEvents

public Map getComponentEvents()

Description copied from interface: IEventListener

Gets all component event mappings.

Specified by:

getComponentEvents in interface IEventListener

Returns:

Map of component ComponentEventProperty values this component is listening to.

getElementEvents

public ComponentEventProperty getElementEvents(String id)

Gets element bound event properties.

Specified by:

getElementEvents in interface IEventListener

Parameters:

id - The element to get listeners for.

Returns:

The bound element event property container, or null if none exist.

getElementEvents

public Map getElementEvents()

Gets all mapped element events for this component.

Specified by:

getElementEvents in interface IEventListener

Returns:

Mapped elements events, if any.

getFormEvents

public EventBoundListener[] getFormEvents(String formId,
                                          BrowserEvent event)

Returns a list of element / component bound event listeners that were specified as invoking the form component with a matching id to formId of type EventBoundListener .

Specified by:

getFormEvents in interface IEventListener

Parameters:

formId - The form that the event listeners were bound to submit when the event occurs.

event - The event that caused the current invocation.

Returns:

A list of events bound to the specified form, empty if none exist.

hasElementEvents

public boolean hasElementEvents()

Checks if any element events are bound to this component.

Specified by:

hasElementEvents in interface IEventListener

Returns:

True if any element events are mapped from this component.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object