package name: org.richfaces.cdk.annotations

Preface

For type safety, only top-level annotations have particular @Target classifier. Additional  annotations cannot be used anywhere except corresponding attributes of top-level annotations. Most of the top-level annotations has "Jsf" preffix to avoid name conflicts with JSF classes. In the most cases, JavaDoc comments also used to generate descriptions and documentation.

Class-level annotations:

@JsfComponent

or @javax.faces.component.FacesComponent("component.Type"). Because JSF library can check component classes during initialization, @FacesComponent annotation should be used for concrete classes only while @Component supposed to mark abstract classes.

Attributes:

• String type – JSF component-type,  required.
• String  family - JSF component family ( if omitted, family will be inferred from the constant COMPONENT_FAMILY or by naming conventions ).
• String generate - name of the generated component class name.
• @Description description - component description for documentation and IDE
  
• @Test test -  tells CDK to generate unit test for that component.
• @JsfRenderer renderer default renderer for the component.
• @Tag[] tag view tag descriptions ( JSP tag, Facelets tag etc ).
• @Fires[] fires list of events that could be fired from component.
• @Facet[] facets
• String[] attributes defines fragments of faces-config.xml that contain standard attribute definitions. CDK also tries to read META-INF/cdk/attributes/[classname].xml file for all component superclasses and interfaces, therefore it is not necessary to explicit include definitions for UIComponent and any other standard JSF classes. CDK defines couple of its own "urn" namespaces: "urn:resource:" for classpath resources, "urn:config:" for for project configuration folder and "urn:attributes:" for META-INF/cdk/attributes/ in the annotations library.
• Class[] interfaces  defines list of interfaces that should be implemented by the generated class. These interfaces should contain only methods recognized by CDK that is Bean property getters and seters annotaded by the @Attribute or @Facet annotations.
• RendererSpecificComponent[] components - defines list of the third-level renderer specific components and tags. These elements allow to create recommended JSF RichFaces CDK naming conventions  from the single abstract class. In this case, @JsfComponent annotation defines how to generare concrete UIComponent class from the abstract one, and @SubComponent annotations contain information of renderer-specific classes and Tags/Renderers associated with them.

@RendererSpecificComponent

This annotation used by @JsfComponent only to describe second level of the generated component classes. Some properties are shared from the top-level @JsfComponent annotation, that are component family and events.

Attributes:

• String type – JSF component-type. If empty, component type will be inferred by naming conventions
  
• String generate - name of the generated component class name.
• @Description description - component description for documentation and IDE
  
• @Test test -  tells CDK to generate unit test for that component.
• @JsfRenderer renderer default renderer for the component.
• @Tag[] tag view tag descriptions ( JSP tag, Facelets tag etc ).
• @Facet[] facets
• String[] attributes defines fragments of faces-config.xml that contain standard attribute definitions. CDK also tries to read META-INF/cdk/attributes/[classname].xml file for all component superclasses and interfaces, therefore it is not necessary to explicit include definitions for UIComponent and any other standard JSF classes. CDK defines couple of its own "urn" namespaces: "urn:resource:" for classpath resources, "urn:config:" for for project configuration folder and "urn:attributes:" for META-INF/cdk/attributes/ in the annotations library.
• Class[] interfaces  defines list of interfaces that should be implemented by the generated class. These interfaces should contain only methods recognized by CDK that is Bean property getters and seters annotaded by the @Attribute or @Facet annotations.

@JsfBehavior

Attributes:

• String id - JSF behavior id, required.
• String generate - name of generated befavior class
• @Description description
• @Tag[] tag - view tag descriptions (JSP tag, Facelets tag etc).
• @Event[] fires list of events that could be fired from annotated behavior.
• @BehaviorRenderer renderer defines default renderer for that behavior.
• @Test test -  tells CDK to generate unit test for that behavior.
• String[] attributes -  the same as for @JsfComponent.

@JsfConverter

Attributes:

• String id - JSF converter id.
• Class forClass - Java class for which instances annotated converter will be called. One of id or forClass attributes is required.
• String generate - name of generated converter class
• @Description description
• @Tag[] tag - view tag descriptions ( JSP tag, Facelets tag etc ).
• @Test test -  tells CDK to generate unit test for that converter.
• String[] attributes -  the same as for @JsfComponent.

@JsfValidator

Attributes:

• String id - JSF validator id, required.
• String generate - name of generated validator class.
• @Description description
• @Tag[] tag - view tag descriptions ( JSP tag, Facelets tag etc ).
• @Test test -  tells CDK to generate unit test for that validator.
• String[] attributes -  the same as for @JsfComponent.

@JsfRenderer or @FacesRenderer

These annotations marks Java class as the JSF component renderer.

Attributes:

• String type
• String family
• String renderKitId
• @Description description
• String template

@JsfBehaviorRenderer or @FacesBehaviorRenderer

These annotations marks Java class as the JSF component renderer.

Attributes:

• String type
• String renderKitId
• @Description description

@Function

That annotation can be applied to any public static method to define it as EL function.

Attributes:

• String name - function name in taglib. If emply, Java function name used.
• @Description description
• TagType type  - defines for which tag library generate function definition ( Jsp, Facelets or All ).

Second-level annotations

These annotations cannot be used alone but only as values of appropriate attributes of top-level annotations, so tis properly usage can be checked by Java compiler or development tools.

• @Test(generate="component.Test",method="testFoo",type=TestType.DECODE) tells CDK to generate unit test for that component.
• @Renderer("renderer.Type") , @RendererTemplate("/renderer/template.xml") associate renderer with that component. The first one defines independently created renderer, while @RendererTemplate tells CDK to generate renderer class from that template. It is possible to define more than one template with component class using
• @Event(type=MyEvent.class,listener="foo.MyListener",source="foo.MySource") defines event classtes that this component could fire.
• @Description - optional description used by the documentation generator and IDE for element icon,  display name and detailed description. CDK also uses JavaDoc comment for detailed description that lets to have a single source of information and keem project documentation consistent.
• @Tag associates that component with JSF tag with optional TagHandler class.Renderer type should be inferred from template or implicit @Renderer annotation / faces-confit <renderer> element.
  • name="foo"
  • generate="bar.FooHandler",
  • handlerBase=foo.Handler.class,
  • type=TagType.Facelets (None, Jsp, Facelets, All) 'None' is default value. TagHandler class won't be generated if you don't set other value.
  • How can we to set name for jsp tag class?

Attribute level annotations (applicable for getter or setter methods):

@Attribute

Marks Java Bean getter or setter method as JSF attribute. The method can be defined as abstract to let CDK generate concrete implementation with state management code. Attributes:

• boolean literal = false - degines is EL expressions allowed to that attribute or it should be static literal.
• boolean hidden = false - hide attribute from tag.
• boolean readOnly = false - do not generate setter for that attribute.
• boolean passThrough = false defines HTML pass througth attribute that should be encoded directly into appropriate element attribute.
• boolean required = false - marks attribute as required in the tag.
• boolean generate = true - generate concrete getter or setter.
• String aliasFor. defines name of attribute for which marked element is only alias. CDK will generate getters/setters for this attribute which delegate calls to the original attribute methods.
• @Description description
• String  defaultValue
• String suggestedValue - define  values for corresponding faces-config elements which can be used in IDE.
• @EventName[] events - defines behavior event names for that attribute. The only one event can be marked as "default".
• @Signature(returnValue=boolean.class,parameters={Object.class,String.class}) defines Java method signature for attributes that holds MethodExpression  objects.

@Facet annotations.

There are two methods to define component facet. At the class level, developer could use facets attribute of the component annotation. It is also possible to define facet getter/setter methods for facet and mark one of them with @Facet annotation.

Attributes:

Example of the abstract component class:

package foo.component;
@Component(type="foo.Panel",
   generate="foo.component.UIPanel",
@Renderer(type="foo.Renderer",
attributes="urn:defaults:base-component.xml",
fires=@Event(type=foo.bar.CustomEvent.class),
subcomponents={
               @SubComponent(
               type=foo.HtmlBar
               generate="foo.html.HtmlBar",
               tag=@Tag(name="bar"),
               renderer=@Renderer(type="foo.BarRenderer")
          ),
               @SubComponent(
               type=foo.HtmlBaz
               generate="foo.html.HtmlBaz",
               tag=@Tag(name="baz"),
               renderer=@Renderer(type="foo.BazRenderer"),
               interfaces=foo.HtmlDiv.class
          )
     }
)
public abstract class AbstractPanel extends UIComponentBase {

// component property.
@Attribute
public abstract String getLayout()

/**
 * Facet description.
*/
@Facet
public abstract String getHeader();







}