org.apache.tapestry.spec
Class ComponentSpecification

java.lang.Object
  extended by org.apache.tapestry.util.BasePropertyHolder
      extended by org.apache.tapestry.spec.LocatablePropertyHolder
          extended by org.apache.tapestry.spec.ComponentSpecification
All Implemented Interfaces:
ILocatable, ILocationHolder, IComponentSpecification, IPropertyHolder

public class ComponentSpecification
extends LocatablePropertyHolder
implements IComponentSpecification

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

A specification consists of

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.

Version:
$Id: ComponentSpecification.java 243791 2004-02-19 17:38:13Z hlship $
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 addParameter(String name, 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 IAssetSpecification with 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 IBeanSpecification for 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()
           
 List getComponentIds()
          Returns an List of the String names of the IContainedComponents for this component.
 String getDescription()
          Returns the documentation for this component.
 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.
 IResourceLocation getSpecificationLocation()
           
 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 setDescription(String description)
          Sets the documentation for this component.
 void setPageSpecification(boolean pageSpecification)
           
 void setPublicId(String publicId)
           
 void setSpecificationLocation(IResourceLocation 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, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.apache.tapestry.util.IPropertyHolder
getProperty, getPropertyNames, removeProperty, setProperty
 
Methods inherited from interface org.apache.tapestry.ILocationHolder
setLocation
 
Methods inherited from interface org.apache.tapestry.ILocatable
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:
IllegalArgumentException - if the name already exists.

addComponent

public void addComponent(String id,
                         IContainedComponent component)
Specified by:
addComponent in interface IComponentSpecification
Throws:
IllegalArgumentException - if the id is already defined.

addParameter

public void addParameter(String name,
                         IParameterSpecification spec)
Adds the parameter. The name is added as a reserved name.

Specified by:
addParameter in interface IComponentSpecification
Throws:
IllegalArgumentException - 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 IAssetSpecification with 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()
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:
addParameter(String, IParameterSpecification)

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:
addParameter(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:
IllegalArgumentException - if the bean already has a specification.
Since:
1.0.4

getBeanSpecification

public IBeanSpecification getBeanSpecification(String name)
Returns the IBeanSpecification for 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 IResourceLocation getSpecificationLocation()
Specified by:
getSpecificationLocation in interface IComponentSpecification
Since:
3.0

setSpecificationLocation

public void setSpecificationLocation(IResourceLocation 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)