|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT |
@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:
Note that a JSPProperty annotation (on a method) is not processed unless the class is marked with this JSPComponent annotation.
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.
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.
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.
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.
Optional Element Summary | |
---|---|
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). |
String |
clazz
The fully-qualified-name of a concrete component class. |
boolean |
composite
|
boolean |
configExcluded
TODO: this is hopefully unused, and can be deleted. |
String |
defaultEventName
The name of the default client event to be return on method ClientBehaviorHolder.getDefaultEventName(). |
String |
defaultRendererType
Define the renderer-type attribute that (together with "family") is used to look up a renderer for instances of a component. |
String |
desc
A Short description of the purpose of this UIComponent. |
String |
family
The JSF Component Family that this component belongs to. |
String |
implementz
Interfaces that generated classes should implement. |
String |
name
The name of the component in a page. |
String |
serialuid
Serial UID to be put on class when generated. |
String |
tagClass
The name of the JSP Tag class that should be generated for this component. |
String |
tagHandler
Indicate tag handler class used for this component on facelets. |
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). |
String |
type
The type string used to create new instances of this component. |
public abstract String name
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.
public abstract String clazz
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".
public abstract String family
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).
public abstract String type
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.
public abstract String defaultRendererType
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.
public abstract boolean canHaveChildren
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.
public abstract boolean configExcluded
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.
public abstract String tagClass
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?
public abstract String tagSuperclass
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.
public abstract String tagHandler
public abstract String bodyContent
public abstract String desc
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.
public abstract String serialuid
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?
public abstract String implementz
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.
public abstract boolean template
public abstract String defaultEventName
public abstract boolean composite
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT |