org.apache.myfaces.buildtools.maven2.plugin.builder.annotation
Annotation Type JSFComponent


@Documented
@Target(value=TYPE)
@Retention(value=SOURCE)
public @interface JSFComponent

This annotation identifies a class as being a JSF component, an ancestor of one, or a template for one.

A JSF component is a concrete class that is a subclass of UIComponent, and is registered in a faces-config.xml file. It always implements the StateHolder interface, and typically has several properties that can be defined from a view file (jsp, facelets or other similar technology).

The myfaces-builder-plugin uses this annotation information to generate the correct faces-config.xml declarations, thus ensuring that the config declarations are consistent with the code. The plugin can also optionally use this information to generate JSP tag classes, and concrete UIComponent implementations.

This tag can be used in several ways:

Any class or interface marked with this annotation will also have its "metadata" stored in the metadata file that the builder plugin creates and stores in the META-INF directory of the processed project.

Note that a JSPProperty annotation (on a method) is not processed unless the class is marked with this JSPComponent annotation.

Annotating an Interface

When an interface is marked with this annotation, then classes which implement that interface and are themselves marked with this annotation inherit the JSFProperty settings declared on the methods in the interface.

This allows common groups of JSF properties to be defined as an interface, and each JSF component class that is expected to provide those properties simply declares that it implements that interface. The normal java compilation rules ensure that the concrete JSF component class implements all of the methods on the interface, and the builder plugin ensures that the inherited JSFProperty settings are used.

Annotating an Abstract Base Class

When an abstract class is marked with this annotation, and the name attribute is not set, then this is a base class that concrete components can extend. Any JSFProperty settings defined on this class are inherited by subclasses.

Annotating a Concrete Component Class

When a non-abstract class is marked with this annotation, and the name attribute is defined then an entry will be created in the generated faces-config.xml file marking this class as a component.

In addition, a JSP TagHandler class will be created using code-generation and an entry will be created in the generated .tld file so that the tag class can be used from JSP applications.

Annotating a Class for Subclass Generation

When an abstract class is marked with this annotation, the name attribute is defined, and the "clazz" attribute is defined then code-generation will be used to create a concrete UIComponent class which is a subclass of this class. The subclass will be registered in the generated faces-config.xml file, a JSP TagHandler class will be created and registered in the .tld file, etc.

Using code-generation to create a subclass allows automatic generation of the "boilerplate code" that is commonly needed for implementing component property getter/setter methods and the saveState/restoreState methods.

Any abstract property getter/setter methods on the annotated class will have the appropriate implementation automatically written for it in the new subclass. However the parent class can override this for any particular method simply by providing a concrete implementation of the method.

Annotating a Class as a Component Template

When an abstract class is marked with this annotation, the name attribute is set, the clazz attribute is set, and attribute template is set to "true" then code-generation will be used to create a new class that is a "copy" of the source code here. As for "subclass generation", any abstract methods will have an appropriate implementation generated.

This approach allows a component "template" to be written as a normal class (with the usual support tools provided by IDEs etc) while allowing the actual UIComponent classes to have a hierarchy that is completely under the control of the annotations. In particular, this is useful for generating components for a JSF specification implementation, which is very specific about the inheritance hierarchy of the standard component classes.

When using this "template" approach, the annotated class itself can (and probably should be) package-scoped.

Version:
$Revision: 939844 $ $Date: 2010-04-30 17:18:27 -0500 (Fri, 30 Apr 2010) $
Author:
Leonardo Uribe (latest modification by $Author: lu4242 $)

Optional Element Summary
 java.lang.String bodyContent
          Indicate if the element accept inner elements (JSP) or not (empty).
 boolean canHaveChildren
          Indicate if the component is allowed to have other UIComponent instances as children (ie "nested within it" in a page).
 java.lang.String clazz
          The fully-qualified-name of a concrete component class.
 boolean composite
           
 boolean configExcluded
          TODO: this is hopefully unused, and can be deleted.
 java.lang.String defaultEventName
          The name of the default client event to be return on method ClientBehaviorHolder.getDefaultEventName().
 java.lang.String defaultRendererType
          Define the renderer-type attribute that (together with "family") is used to look up a renderer for instances of a component.
 java.lang.String desc
          A Short description of the purpose of this UIComponent.
 java.lang.String family
          The JSF Component Family that this component belongs to.
 java.lang.String implementz
          Interfaces that generated classes should implement.
 java.lang.String name
          The name of the component in a page.
 java.lang.String serialuid
          Serial UID to be put on class when generated.
 java.lang.String tagClass
          The name of the JSP Tag class that should be generated for this component.
 java.lang.String tagHandler
          Indicate tag handler class used for this component on facelets.
 java.lang.String tagSuperclass
          Tag super class that the generated tag class extends.
 boolean template
          Indicate if the pattern used to generate component class code is template (true) or subclass (false).
 java.lang.String type
          The type string used to create new instances of this component.
 

name

public abstract java.lang.String name
The name of the component in a page. This is the name by which the component will be referenced by the used (the name used to register JSP TagHandlers for example). For example: "mycomp".

When a project is generating components that live in more than one namespace, then the name can optionally include a namespace prefix, for example "x:mycomp".

If a class is marked with the JSFComponent annotation, but does not define the name attribute then it is a "base class" that other UIComponent classes can extend (and therefore inherit any JSFProperty definitions from the base class), but is not a component that can be instantiated.

This property should never be set for an interface.

This property should only be set for an abstract class when code generation is expected to automatically create a component based on this one (ie when clazz and perhaps template are set).

This attribute is not inheritable.

Default:
""

clazz

public abstract java.lang.String clazz
The fully-qualified-name of a concrete component class.

This attribute is only relevant when "name" is also set, ie the annotation is indicating that a component is really being declared.

When this attribute is not defined then it is assumed that this annotated class is the actual component class.

When this attribute is set to something other than the name of the annotated class then the specified class is the one that the JSF component registration in faces-config.xml will refer to. And if that class does not exist in the classpath (which will normally be the case) then code-generation will be triggered to create it.

This attribute is not inheritable.

The doclet-annotation equivalent of this attribute is named "class".

Default:
""

family

public abstract java.lang.String family
The JSF Component Family that this component belongs to.

A UIComponent instance's "family" setting is used together with a "renderer-type" to find a renderer for the component (see method UIComponent.getRenderer). Each Renderer implementation is registered in a faces-config.xml file using a (component-family, renderer-type) pair.

If this attribute is not set then the builder plugin will look for a constant on the class with name COMPONENT_FAMILY. It is an error if a concrete component has no such setting (but the value can be inherited from an ancestor class).

Default:
""

type

public abstract java.lang.String type
The type string used to create new instances of this component.

Components are registered in faces-config.xml using this type value, and new instances are created via Application.createComponent(type).

If this attribute is not set, then the builder plugin will look for a constant on the class with name COMPONENT_TYPE. It is an error if a component has no such setting.

This should only be set on concrete component classes (or classes for which code generation creates a concrete component class). The attribute is not inheritable.

Default:
""

defaultRendererType

public abstract java.lang.String defaultRendererType
Define the renderer-type attribute that (together with "family") is used to look up a renderer for instances of a component.

See attribute "family" for more details.

If this attribute is not defined, the builder plugin looks for a constant on the class with name DEFAULT_RENDERER_TYPE. It is an error if a concrete component has no such setting (but the value can be inherited from an ancestor class).

This attribute is inheritable.

Default:
""

canHaveChildren

public abstract boolean canHaveChildren
Indicate if the component is allowed to have other UIComponent instances as children (ie "nested within it" in a page).

This information can be inserted into .tld files and similar to present users with an error message if an attempt is made to define child components for a component that does not support them.

Code generation might also use this information to ensure that an exception is thrown if an attempt to add child components occurs at runtime.

Note that this is related to, but not quite the same as, the "bodyContent" attribute. That attribute prevents anything being nested inside the component in the page, while this prevents UIComponents being nested. ?? TODO: but in JSF1.2, isn't static text a transient child??

This attribute is inheritable.

Default:
false

configExcluded

public abstract boolean configExcluded
TODO: this is hopefully unused, and can be deleted.

Indicate that this component should not be defined on faces-config.xml. Anyway, if this is true or false does not have any significative impact.

Default:
false

tagClass

public abstract java.lang.String tagClass
The name of the JSP Tag class that should be generated for this component.

It is an error to set this attribute if the annotated class is not a concrete JSF component.

TODO: ? WHat happens if a class is a concrete component but this is not set? Is a tagClass name automatically created? Or is no tag class created?

Default:
""

tagSuperclass

public abstract java.lang.String tagSuperclass
Tag super class that the generated tag class extends.

The generated tag class for this component may need to be a subclass of different tag base classes depending upon the type of this component. For example, the JSF standard provides the following tag classes:

This is optional; when not defined, the standard UIComponentTag class is used. This is appropriate for most JSF components.

Default:
""

tagHandler

public abstract java.lang.String tagHandler
Indicate tag handler class used for this component on facelets.

Default:
""

bodyContent

public abstract java.lang.String bodyContent
Indicate if the element accept inner elements (JSP) or not (empty).

Default:
""

desc

public abstract java.lang.String desc
A Short description of the purpose of this UIComponent.

This information is output into the .tld and faces-config.xml files as help for users of this component, and may be displayed by IDEs and similar tools.

If not set, then the javadoc "summary" sentence for the class will be used. If there is no javadoc for the class then the description will be an empty string (but that will never happen, right?).

Note that tld or faces-config files also have a "long description" field. That value is always the complete javadoc for the component class.

This attribute is not inheritable.

Default:
""

serialuid

public abstract java.lang.String serialuid
Serial UID to be put on class when generated.

This should be set only for "component template" code generation, ie where the superClass attribute is set. In this case, the generated class will have a serialVersionUID constant defined which is set to this value.

TODO: is this valid? Why can't the code-generation just add a serialUid value based upon what version of the template was used? Maybe because the template generates different stuff based upon what attributes are defined here?

Default:
""

implementz

public abstract java.lang.String implementz
Interfaces that generated classes should implement.

Used only when "component template" code generation is used. When defined, then the generated class will implement the listed interfaces in addition to the interfaces that this annotated class implements.

Default:
""

template

public abstract boolean template
Indicate if the pattern used to generate component class code is template (true) or subclass (false).

Default:
false

defaultEventName

public abstract java.lang.String defaultEventName
The name of the default client event to be return on method ClientBehaviorHolder.getDefaultEventName(). This property is JSF 2.0 specific, and the component must implement javax.faces.component.behavior.ClientBehaviorHolder interface.

Since:
1.0.4
Default:
""

composite

public abstract boolean composite
Since:
1.0.5
Default:
false


Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.