org.apache.tapestry.spec
Interface IComponentSpecification

All Superinterfaces:

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

All Known Implementing Classes:

ComponentSpecification

public interface IComponentSpecification
extends IPropertyHolder, org.apache.hivemind.LocationHolder, org.apache.hivemind.Locatable, IEventListener

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

A specification consists of

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

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:

glongman@intelligentworks.com

See Also:

IComponent, IContainedComponent, IComponentSpecification, IPageLoader

Method Summary

void	addAsset(String name, IAssetSpecification asset)
void	addBeanSpecification(String name, IBeanSpecification specification)
void	addComponent(String id, IContainedComponent 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.
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).
List	getComponentIds() Returns an List of the String names of the IContainedComponents for this component.
String	getDescription() Returns the documentation for this component.
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	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	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)

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

Methods inherited from interface org.apache.tapestry.spec.IEventListener

addElementEventListener, addEventListener, connectAutoSubmitEvents, getComponentEvents, getComponentEvents, getElementEvents, getElementEvents, getFormEvents, hasElementEvents, rewireComponentId

Method Detail

addAsset

void addAsset(String name,
              IAssetSpecification asset)

Throws:

IllegalArgumentException - if the name already exists.

addComponent

void addComponent(String id,
                  IContainedComponent component)

Throws:

IllegalArgumentException - if the id is already defined.

addParameter

void addParameter(IParameterSpecification spec)

Adds the parameter. The parameter name and aliases are added as a reserved name. The code assumes that the parameter specification will not be subsequently changed.

Throws:

IllegalArgumentException - if the name already exists.

getAllowBody

boolean getAllowBody()

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

See Also:

setAllowBody(boolean)

getAllowInformalParameters

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.

See Also:

setAllowInformalParameters(boolean)

getAsset

IAssetSpecification getAsset(String name)

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

See Also:

addAsset(String,IAssetSpecification)

getAssetNames

List getAssetNames()

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

getComponent

IContainedComponent getComponent(String id)

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

See Also:

addComponent(String, IContainedComponent)

getComponentClassName

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).

getComponentIds

List getComponentIds()

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

See Also:

addComponent(String, IContainedComponent)

getParameter

IParameterSpecification getParameter(String name)

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

See Also:

addParameter(IParameterSpecification)

getRequiredParameters

Collection getRequiredParameters()

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

Since:

4.0

getParameterNames

List getParameterNames()

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

See Also:

addParameter(IParameterSpecification)

setAllowBody

void setAllowBody(boolean value)

setAllowInformalParameters

void setAllowInformalParameters(boolean value)

setComponentClassName

void setComponentClassName(String value)

addBeanSpecification

void addBeanSpecification(String name,
                          IBeanSpecification specification)

Throws:

IllegalArgumentException - if the bean already has a specification.

Since:

1.0.4

getBeanSpecification

IBeanSpecification getBeanSpecification(String name)

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

Since:

1.0.4

getBeanNames

Collection getBeanNames()

Returns an unmodifiable collection of the names of all beans.

addReservedParameterName

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.

Since:

1.0.5

isReservedParameterName

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.

Since:

1.0.5

getDescription

String getDescription()

Returns the documentation for this component.

Since:

1.0.9

setDescription

void setDescription(String description)

Sets the documentation for this component.

Since:

1.0.9

getPublicId

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.

Since:

2.2

setPublicId

void setPublicId(String publicId)

Since:

2.2 *

isPageSpecification

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.

Since:

2.2

setPageSpecification

void setPageSpecification(boolean pageSpecification)

Since:

2.2 *

getSpecificationLocation

org.apache.hivemind.Resource getSpecificationLocation()

Since:

3.0 *

setSpecificationLocation

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

Since:

3.0 *

addPropertySpecification

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).

Since:

3.0

getPropertySpecificationNames

List getPropertySpecificationNames()

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

Since:

3.0

getPropertySpecification

IPropertySpecification getPropertySpecification(String name)

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

Since:

3.0

See Also:

addPropertySpecification(IPropertySpecification)

addInjectSpecification

void addInjectSpecification(InjectSpecification spec)

Adds a InjectSpecification.

Since:

4.0

getInjectSpecifications

List getInjectSpecifications()

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

Since:

4.0

isDeprecated

boolean isDeprecated()

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

Since:

4.0

setDeprecated

void setDeprecated(boolean deprecated)

Since:

4.0

getReservedParameterNames

Set getReservedParameterNames()

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).

Since:

4.0