org.zkoss.zk.ui.metainfo.impl
Class ComponentDefinitionImpl

java.lang.Object
  org.zkoss.zk.ui.metainfo.impl.ComponentDefinitionImpl

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, ComponentDefinition

Direct Known Subclasses:

MacroDefinition

public class ComponentDefinitionImpl
extends java.lang.Object
implements ComponentDefinition, java.io.Serializable

An implementation of ComponentDefinition.

Note: it is not thread safe. Thus, it is better to clone(org.zkoss.zk.ui.metainfo.LanguageDefinition, java.lang.String) and then modifying the cloned instance if you want to change it concurrently.

Author:

tomyeh

See Also:

Serialized Form

Field Summary

Fields inherited from interface org.zkoss.zk.ui.metainfo.ComponentDefinition

ZK

Constructor Summary

ComponentDefinitionImpl(LanguageDefinition langdef, PageDefinition pgdef, java.lang.String name, java.lang.Class cls)
Constructs a native component, i.e., a component implemented by a Java class.

ComponentDefinitionImpl(LanguageDefinition langdef, PageDefinition pgdef, java.lang.String name, java.lang.String clsnm)
Constructs a native component, i.e., a component implemented by a Java class.

Method Summary

void	addAnnotation(java.lang.String annotName, java.util.Map annotAttrs) Associates an annotation to this component definition.
void	addAnnotation(java.lang.String propName, java.lang.String annotName, java.util.Map annotAttrs) Adds an annotation to the specified proeprty of this component definition.
void	addCustomAttribute(java.lang.String name, java.lang.String value) Adds a custom attribute.
void	addMold(java.lang.String name, ComponentRenderer renderer) Deprecated.
void	addMold(java.lang.String name, ComponentRenderer renderer, java.lang.String z2cURI) Adds a mold based on ComponentRenderer.
void	addMold(java.lang.String name, java.lang.String moldURI) Deprecated.
void	addMold(java.lang.String name, java.lang.String moldURI, java.lang.String z2cURI) Adds a mold based on an URI.
void	addProperty(java.lang.String name, java.lang.String value) Adds a property initializer.
void	applyProperties(Component comp) Applies the properties and custom attributes defined in this definition to the specified component.
java.lang.Object	clone() Clones this component definition.
ComponentDefinition	clone(LanguageDefinition langdef, java.lang.String name) Clones this definition and assins with the specified language definition and name.
java.util.Map	evalProperties(java.util.Map propmap, Page owner, Component parent) Evaluates and retrieves properties to the specified map.
AnnotationMap	getAnnotationMap() Returns the annotation map defined in this definition, or null if no annotation is ever defined.
java.lang.String	getApply() Returns the apply attribute that is a list of Composer class names or EL expressions returning classes, class names or composer instances, or null if no apply attribute.
java.lang.String	getCurrentDirectory() Returns the current directory which is used to convert a relative URI to absolute, or null if not available.
java.net.URL	getDeclarationURL() Returns the URL where this component definition is declared, or null if not available.
java.lang.Object	getImplementationClass() Returns the class (Class) or the class name (String) that implements the component.
LanguageDefinition	getLanguageDefinition() Returns the language definition, or null if it is a temporty definition belonging to a page.
java.lang.String	getMacroURI() Returns the macro URI, or null if not a macro.
java.util.Collection	getMoldNames() Returns a readonly collection of mold names supported by this definition.
java.lang.Object	getMoldURI(Component comp, java.lang.String name) Returns the URI (String) or an instance of ComponentRenderer of the mold, or null if no such mold available.
java.lang.String	getName() Returns name of this component definition (never null).
ExValue[]	getParsedApply() Return the parsed expressions of the apply attribute.
java.lang.String	getTextAs() Returns the property name to which the text enclosed within the element (associated with this component definition) is assigned to.
java.lang.String	getZ2CURI(Component comp, java.lang.String name) Returns the URI of the ZCS-to-CSS converter for the specified mold.
boolean	hasMold(java.lang.String name) Returns whether the specified mold exists.
boolean	isBlankPreserved() Returns whether to preserve the blank text.
boolean	isInlineMacro() Returns whether this is an inline macro.
boolean	isInstance(Component comp) Returns whether a component belongs to this definition.
boolean	isMacro() Returns whether this is a macro component.
boolean	isNative() Returns whether this is used for the native namespace.
Component	newInstance(java.lang.Class cls) Creates an component of this definition.
Component	newInstance(Page page, java.lang.String clsnm) Creates an component of this definition.
static ComponentDefinition	newMacroDefinition(LanguageDefinition langdef, PageDefinition pgdef, java.lang.String name, java.lang.Class cls, java.lang.String macroURI, boolean inline) Constructs a macro component definition.
static ComponentDefinition	newNativeDefinition(LanguageDefinition langdef, java.lang.String name, java.lang.Class cls) Constructs a native component definition.
java.lang.Class	resolveImplementationClass(Page page, java.lang.String clsnm) Resolves and returns the class that implements the component.
void	setApply(java.lang.String apply) Sets the apply attribute that is is a list of Composer class or EL expressions returning classes, class names or composer instances.
void	setBlankPreserved(boolean preserve) Sets whether to preserve the blank text.
void	setCurrentDirectory(java.lang.String curdir) Sets the current directory which is used to convert a relative URI to absolute.
void	setDeclarationURL(java.net.URL url) Sets the URI where this definition is declared.
void	setImplementationClass(java.lang.Class cls) Sets the class to implements the component.
void	setImplementationClass(java.lang.String clsnm) Sets the class name to implements the component.
void	setTextAs(java.lang.String propnm) Sets the property name to which the text enclosed within the element (associated with this component definition) is assigned to.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ComponentDefinitionImpl

public ComponentDefinitionImpl(LanguageDefinition langdef,
                               PageDefinition pgdef,
                               java.lang.String name,
                               java.lang.Class cls)

Constructs a native component, i.e., a component implemented by a Java class.

Note; if both langdef and pgdef are null, it must be a reserved component.

Parameters:

langdef - the language definition. It is null if it is defined as part of a page definition

pgdef - the page definition. It is null if it is defined as part of a language definition. doesn't belong to any language.

cls - the implementation class.

Since:

3.0.0

ComponentDefinitionImpl

public ComponentDefinitionImpl(LanguageDefinition langdef,
                               PageDefinition pgdef,
                               java.lang.String name,
                               java.lang.String clsnm)

Constructs a native component, i.e., a component implemented by a Java class.

Note; if both langdef and pgdef are null, it must be a reserved component.

Parameters:

langdef - the language definition. It is null if it is defined as part of a page definition

pgdef - the page definition. It is null if it is defined as part of a language definition. doesn't belong to any language.

clsnm - the implementation class.

Since:

3.0.8

Method Detail

newMacroDefinition

public static final ComponentDefinition newMacroDefinition(LanguageDefinition langdef,
                                                           PageDefinition pgdef,
                                                           java.lang.String name,
                                                           java.lang.Class cls,
                                                           java.lang.String macroURI,
                                                           boolean inline)

Constructs a macro component definition. It is the component definition used to implement the macros.

Parameters:

langdef - the language definition. It is null if it is defined as part of a page definition

pgdef - the page definition. It is null if it is defined as part of a language definition.

Since:

3.0.0

newNativeDefinition

public static final ComponentDefinition newNativeDefinition(LanguageDefinition langdef,
                                                            java.lang.String name,
                                                            java.lang.Class cls)

Constructs a native component definition. It is the component definition used to implement the native namespace.

Parameters:

langdef - the language definition. It cannot be null.

Since:

3.0.0

addCustomAttribute

public void addCustomAttribute(java.lang.String name,
                               java.lang.String value)

Adds a custom attribute.

addAnnotation

public void addAnnotation(java.lang.String annotName,
                          java.util.Map annotAttrs)

Associates an annotation to this component definition.

Parameters:

annotName - the annotation name (never null, nor empty).

annotAttrs - a map of attributes, or null if no attribute at all. The attribute must be in a pair of strings (String name, String value).

addAnnotation

public void addAnnotation(java.lang.String propName,
                          java.lang.String annotName,
                          java.util.Map annotAttrs)

Adds an annotation to the specified proeprty of this component definition.

Parameters:

propName - the property name (never nul, nor empty).

annotName - the annotation name (never null, nor empty).

annotAttrs - a map of attributes, or null if no attribute at all. The attribute must be in a pair of strings (String name, String value).

getCurrentDirectory

public java.lang.String getCurrentDirectory()

Returns the current directory which is used to convert a relative URI to absolute, or null if not available.

setCurrentDirectory

public void setCurrentDirectory(java.lang.String curdir)

Sets the current directory which is used to convert a relative URI to absolute.

Parameters:

curdir - the current directory; null to ignore.

setTextAs

public void setTextAs(java.lang.String propnm)

Sets the property name to which the text enclosed within the element (associated with this component definition) is assigned to.

Default: null (means to create a Label component)

Parameters:

propnm - the property name. If empty (""), null is assumed.

Since:

3.0.0

See Also:

getTextAs()

setBlankPreserved

public void setBlankPreserved(boolean preserve)

Sets whether to preserve the blank text. If false, the blank text (a non-empty string consisting of whitespaces) are ignored. If true, they are converted to a label child.

Default: false.

Since:

3.5.0

See Also:

isBlankPreserved()

setDeclarationURL

public void setDeclarationURL(java.net.URL url)

Sets the URI where this definition is declared.

Parameters:

url - the URL. If null, it means not available.

Since:

3.0.3

getLanguageDefinition

public LanguageDefinition getLanguageDefinition()

Description copied from interface: ComponentDefinition

Returns the language definition, or null if it is a temporty definition belonging to a page.

Specified by:

getLanguageDefinition in interface ComponentDefinition

getName

public java.lang.String getName()

Description copied from interface: ComponentDefinition

Returns name of this component definition (never null). It is unique in the same language, LanguageDefinition, if it belongs to a language, i.e., ComponentDefinition.getLanguageDefinition() is not null.

Specified by:

getName in interface ComponentDefinition

getTextAs

public java.lang.String getTextAs()

Description copied from interface: ComponentDefinition

Returns the property name to which the text enclosed within the element (associated with this component definition) is assigned to.

Default: null (means to create a Label component as the child)

For example, if ComponentDefinition.getTextAs() returns null, then a Label component is created as a child of comp with the "Hi Text" value in the following example:

<comp>
  Hi Text
</comp>

In other words, it is equivalent to

<comp>
  <label value="Hi Text"/>
</comp>

On the other hand, if ComponentDefinition.getTextAs() returns a non-empty string, say, "content", then "Hi Text" is assigned to the content property of comp. In other words, it is equivalent to

<comp content="Hi Text"/>
</comp>

It is also the same as

<comp>
  <attribute name="content"/>
  Hi Text
  </attribute>
</comp>

To enable it, you can declare text-as in the component definition in lang.xml or lang-addon.xml:

<component>
  <component-name>html</component-name>
  <text-as>content</text-as>
...

Specified by:

getTextAs in interface ComponentDefinition

isBlankPreserved

public boolean isBlankPreserved()

Description copied from interface: ComponentDefinition

Returns whether to preserve the blank text. If false, the blank text (a non-empty string consisting of whitespaces) are ignored. If true, they are converted to a label child.

Default: false.

Specified by:

isBlankPreserved in interface ComponentDefinition

isMacro

public boolean isMacro()

Description copied from interface: ComponentDefinition

Returns whether this is a macro component.

Specified by:

isMacro in interface ComponentDefinition

See Also:

ComponentDefinition.getMacroURI()

getMacroURI

public java.lang.String getMacroURI()

Description copied from interface: ComponentDefinition

Returns the macro URI, or null if not a macro.

Specified by:

getMacroURI in interface ComponentDefinition

isInlineMacro

public boolean isInlineMacro()

Description copied from interface: ComponentDefinition

Returns whether this is an inline macro. If false, you have to examine ComponentDefinition.isMacro() to see whether it is a regular macro.

Specified by:

isInlineMacro in interface ComponentDefinition

isNative

public boolean isNative()

Description copied from interface: ComponentDefinition

Returns whether this is used for the native namespace.

Specified by:

isNative in interface ComponentDefinition

See Also:

LanguageDefinition.getNativeDefinition()

getImplementationClass

public java.lang.Object getImplementationClass()

Description copied from interface: ComponentDefinition

Returns the class (Class) or the class name (String) that implements the component.

If a string is returned, the real class may depend on which page a component will be created to. Reason: the zscript interpreter is associated with a page and it may define classes upon evaluating a page.

Specified by:

getImplementationClass in interface ComponentDefinition

setImplementationClass

public void setImplementationClass(java.lang.Class cls)

Description copied from interface: ComponentDefinition

Sets the class to implements the component.

Note: currently, classes specified in lang.xml or lang-addon.xml must be resolved when loading the files. However, classes specified in a page (by use of class or use attributes) might be resolved later because it might be defined by zscript.

Specified by:

setImplementationClass in interface ComponentDefinition

setImplementationClass

public void setImplementationClass(java.lang.String clsnm)

Description copied from interface: ComponentDefinition

Sets the class name to implements the component. Unlike ComponentDefinition.setImplementationClass(Class), the class won't be resolved until ComponentInfo.newInstance(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Component) or ComponentDefinition.getImplementationClass() is used. In other words, the class can be provided later (thru, usually, zscript).

Specified by:

setImplementationClass in interface ComponentDefinition

newInstance

public Component newInstance(Page page,
                             java.lang.String clsnm)

Description copied from interface: ComponentDefinition

Creates an component of this definition.

Note: this method doesn't invoke ComponentDefinition.applyProperties(org.zkoss.zk.ui.Component). It is caller's job to apply these properties if necessary. Since the value of a property might depend on the component tree, it is better to assign the component with a proper parent before calling ComponentDefinition.applyProperties(org.zkoss.zk.ui.Component).

Similarly, this method doesn't attach the component to the specified page. Developers may or may not add it to a page or a parent.

An application developer can invoke UiFactory.newComponent(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.metainfo.ComponentInfo) instead of ComponentDefinition.newInstance(org.zkoss.zk.ui.Page, java.lang.String), since a deployer might customize the way to create components by providing an implementation of UiFactory. In additions, it also invokes ComponentDefinition.applyProperties(org.zkoss.zk.ui.Component) assigning page/parent.

On the other hand, this method is 'low-level'. It simply resolves the implementation class by use of ComponentDefinition.resolveImplementationClass(org.zkoss.zk.ui.Page, java.lang.String), and then uses it to create an instance.

Specified by:

newInstance in interface ComponentDefinition

Parameters:

page - the page that is used to resolve the implementation class. It is used only this definition is associated with a class name by ComponentDefinition.setImplementationClass(String), or clsnm is not null. Note: this method won't attach the component to the specified page. It can be null if ComponentDefinition.getImplementationClass() returns a Class instance, and clsnm is null.

clsnm - [optional] If specified, clsnm is used instead of ComponentDefinition.getImplementationClass(). In other words, it overrides the default class.

Returns:

the new component (never null)

newInstance

public Component newInstance(java.lang.Class cls)

Description copied from interface: ComponentDefinition

Creates an component of this definition. Refer to ComponentDefinition.newInstance(Page, String). They are the same except this method accepts the class directly, while ComponentDefinition.newInstance(Page, String) invokes ComponentDefinition.resolveImplementationClass(org.zkoss.zk.ui.Page, java.lang.String) to resolve the class first.

Specified by:

newInstance in interface ComponentDefinition

Returns:

the new component (never null)

isInstance

public boolean isInstance(Component comp)

Description copied from interface: ComponentDefinition

Returns whether a component belongs to this definition.

If ComponentDefinition.resolveImplementationClass(org.zkoss.zk.ui.Page, java.lang.String) failed to resolve, true is returned!

Specified by:

isInstance in interface ComponentDefinition

resolveImplementationClass

public java.lang.Class resolveImplementationClass(Page page,
                                                  java.lang.String clsnm)
                                           throws java.lang.ClassNotFoundException

Description copied from interface: ComponentDefinition

Resolves and returns the class that implements the component.

Unlike ComponentDefinition.getImplementationClass(), this method will resolve a class name (String) to a class (Class), if necessary. In addition, if the clsnm argument is specified, it is used instead of ComponentDefinition.getImplementationClass(). In other words, it overrides the default class.

Specified by:

resolveImplementationClass in interface ComponentDefinition

Parameters:

page - the page to check whether the class is defined in its interpreters. Ignored if null. This method will search the class loader of the current thread. If not found, it will search the interpreters of the specifed page (Page.getLoadedInterpreters()). Note: this method won't attach the component to the specified page.

clsnm - [optional] If specified, clsnm is used instead of ComponentDefinition.getImplementationClass(). In other words, it overrides the default class.

Throws:

java.lang.ClassNotFoundException - if the class not found

getAnnotationMap

public AnnotationMap getAnnotationMap()

Description copied from interface: ComponentDefinition

Returns the annotation map defined in this definition, or null if no annotation is ever defined.

Specified by:

getAnnotationMap in interface ComponentDefinition

getApply

public java.lang.String getApply()

Description copied from interface: ComponentDefinition

Returns the apply attribute that is a list of Composer class names or EL expressions returning classes, class names or composer instances, or null if no apply attribute.

Specified by:

getApply in interface ComponentDefinition

See Also:

ComponentDefinition.getParsedApply()

setApply

public void setApply(java.lang.String apply)

Description copied from interface: ComponentDefinition

Sets the apply attribute that is is a list of Composer class or EL expressions returning classes, class names or composer instances.

Specified by:

setApply in interface ComponentDefinition

Parameters:

apply - the attribute this is a list of Composer class or EL expressions El expressions are allowed, but self means the parent, if available; or page, if no parent at all. (Note: the component is not created yet when the apply attribute is evaluated).

getParsedApply

public ExValue[] getParsedApply()

Description copied from interface: ComponentDefinition

Return the parsed expressions of the apply attribute.

Specified by:

getParsedApply in interface ComponentDefinition

See Also:

ComponentDefinition.getApply()

getDeclarationURL

public java.net.URL getDeclarationURL()

Description copied from interface: ComponentDefinition

Returns the URL where this component definition is declared, or null if not available.

Specified by:

getDeclarationURL in interface ComponentDefinition

addProperty

public void addProperty(java.lang.String name,
                        java.lang.String value)

Description copied from interface: ComponentDefinition

Adds a property initializer. It will initialize a component when created with is definition.

Specified by:

addProperty in interface ComponentDefinition

Parameters:

name - the member name. The component must have a valid setter for it.

value - the value. It might contain expressions (${}).

applyProperties

public void applyProperties(Component comp)

Description copied from interface: ComponentDefinition

Applies the properties and custom attributes defined in this definition to the specified component.

Note: annotations are applied to the component when a component is created. So, this method doesn't and need not to copy them. See also AbstractComponent.AbstractComponent().

Specified by:

applyProperties in interface ComponentDefinition

evalProperties

public java.util.Map evalProperties(java.util.Map propmap,
                                    Page owner,
                                    Component parent)

Description copied from interface: ComponentDefinition

Evaluates and retrieves properties to the specified map.

Specified by:

evalProperties in interface ComponentDefinition

Parameters:

propmap - the map to store the retrieved properties. If null, a HashMap instance is created. (String name, Object value).

owner - the owner page; used if parent is null

parent - the parent

addMold

public void addMold(java.lang.String name,
                    java.lang.String moldURI,
                    java.lang.String z2cURI)

Description copied from interface: ComponentDefinition

Adds a mold based on an URI.

Specified by:

addMold in interface ComponentDefinition

moldURI - an URI of the mold; never null nor empty. If it starts with "class:", the following substring is assumed to be the class name of ComponentRenderer, and then it invokes ComponentDefinition.addMold(String, ComponentRenderer). If not staring with "class:", it is pure an URI, and it may contain XEL expressions.

z2cURI - the URI of ZCS-to-CSS converter. Ignored if null.

addMold

public void addMold(java.lang.String name,
                    ComponentRenderer renderer,
                    java.lang.String z2cURI)

Description copied from interface: ComponentDefinition

Adds a mold based on ComponentRenderer.

Specified by:

addMold in interface ComponentDefinition

renderer - a component renderer. It is shared by all component instances belonging to this definition.

z2cURI - the URI of ZCS-to-CSS converter. Ignored if null.

addMold

public void addMold(java.lang.String name,
                    java.lang.String moldURI)

Deprecated.

Specified by:

addMold in interface ComponentDefinition

addMold

public void addMold(java.lang.String name,
                    ComponentRenderer renderer)

Deprecated.

Specified by:

addMold in interface ComponentDefinition

getMoldURI

public java.lang.Object getMoldURI(Component comp,
                                   java.lang.String name)

Description copied from interface: ComponentDefinition

Returns the URI (String) or an instance of ComponentRenderer of the mold, or null if no such mold available. In other words, if a String instance is returned, it is the URI of the mold. If a ComponentRenderer instance is returned, it is the object responsible to handle the generation of the component's output.

If the mold URI contains an expression, it will be evaluated first before returning.

Specified by:

getMoldURI in interface ComponentDefinition

name - the mold name

Returns:

an URI in String, or a ComponentRenderer, as of release 3.0.0

See Also:

AbstractComponent.redraw(java.io.Writer)

hasMold

public boolean hasMold(java.lang.String name)

Description copied from interface: ComponentDefinition

Returns whether the specified mold exists.

Specified by:

hasMold in interface ComponentDefinition

getMoldNames

public java.util.Collection getMoldNames()

Description copied from interface: ComponentDefinition

Returns a readonly collection of mold names supported by this definition.

Specified by:

getMoldNames in interface ComponentDefinition

getZ2CURI

public java.lang.String getZ2CURI(Component comp,
                                  java.lang.String name)

Description copied from interface: ComponentDefinition

Returns the URI of the ZCS-to-CSS converter for the specified mold.

ZCS is ZK cacasding style that allows developers to customize CSS with the component names.

Specified by:

getZ2CURI in interface ComponentDefinition

name - the mold name

clone

public ComponentDefinition clone(LanguageDefinition langdef,
                                 java.lang.String name)

Description copied from interface: ComponentDefinition

Clones this definition and assins with the specified language definition and name.

Specified by:

clone in interface ComponentDefinition

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

clone

public java.lang.Object clone()

Description copied from interface: ComponentDefinition

Clones this component definition. You rarely invoke this method directly. Rather, use ComponentDefinition.clone(LanguageDefinition, String).

Note: the caller usually has to change the component name, and then assign to a language definition (LanguageDefinition) or a page definition (PageDefinition).

Specified by:

clone in interface ComponentDefinition

Overrides:

clone in class java.lang.Object

Returns:

the new component definition by cloning from this definition.