This article is part of RichFaces JSF 2.0 migration . CDK development status 08-26-09

Although JSF 2.0 has a new declarative components, it seems too limited for complex components ( like Tree, data tables and so on ) development. Also, it is still necessary to generate special getters and state saving-restore methods, add/removeListener methods, custom tag handlers and so on. The main purpose for the CDK is speeding up RichFaces components development, while it also could be convinient public tool for the third-party component developers.

Goal: Use minimum of files to build component.

In the perfect situation, a component developer has to write two files only: Abstract component class that implements component functionality and JSF renderer template for visual representation. The CDK has to generate all necessary JSF stuff ( concrete component class, renderer-specific component class, renderer class, faces-config.xml file, tag handler class and taglib file ) and some additional like JUnit tests that can check compatibility with JSF contracts ( no exceptions from lifecycle methods, properly state saving, event processing ) and Taglib documentation..

Coding by convention

To avoid a lot of similar configuration elements, CDK uses its own RichFaces CDK naming conventions for classes, components and tags. Component developer may omit some default values, in that case they will be inferred by naming conventions.

Configuration

RichFaces CDK annotations. CDK uses Annotation Tools Processor ( APT ) and JDK 6 JavaCompiler API to parse sourse code and build configuration model. Although CDK itself can be run under JDK 1.6 only, generated code does not contain any version specific syntax and can be compiled by any Java compiler.

CDK recognizes all faces-config elements and RichFaces CDK faces-config extensions which defined in the separate namespace and have its own schema. CDK uses JAXB library to marshal that configuration into XML model. To avoid repeated parts for identical elements, these elements can be extracted into separate files and included using XInclude. Important notice: CDK uses Xerces XML parser that does not recognize XInclude 'xpointer' namespace. XML parser recognizes same 'urn:' protocols as @Attributes annotation. NB: ALPHA1 release does not include definitions for standard attributes.

XML configuration, parsed on the second stage of build cycle applied to annotations-based model, therefore it allows to overwrite or extend information from annotations.

Library-wide configuration information can be provided from build tool. See Maven CDK plugin configuration for example.

Renderer Template

The main purpose for renderer template language was close a gap between HTML design and Java code, because it is very hard to convert complex enougth HTML code into the sequence of ResponseWriter calls and such code become unmaintable. The JSF 2.0 composite components has a different purpose as tool to combine existing components into reusable templates, but RichFaces project works on lowest level. Because of these differences it is not possible to use VDL-only tags for the renderer template language, so CDK extends it.

TBD: template language syntax.

Architecture

CDK contains a couple of projects: generator, annotations, maven-cdk-plugin. The Generator project contains main CDK code that could be used with different tools: Maven, Apache Ant and even integrated with IDE as Annotation Tools Processor. Annotations library contains the Java annotations and xml files with configuration of the standard attributes that used by the CDK annotations processor. Particular JSF component project also needs these annotations to compile java code but it does not required at runtime.

Generator.

CdkGeneratorArchitecture designed close to Model-View-Controller pattern. The model encapsulates all information necessary to build JSF files from different sources: Java Annotations, XML configuration and, in future, cached results that can be used to speed-up build process. The model provides methods for manipulation its content, that keeps references betveen objects and checks model restrictions ( including CDK naming conventions ), visitor methods. Controller itself implemented by using dependency injection framework ( Google Guice ) that instantiates most controller-related objects and put all of them together.

Maven-Cdk-Plugin

Maven plugin is only tool included in the ALPHA1 release. It contains goals to run tamplate compiler only and whole build as well. Plugin configuration was not finished for ALPHA1 release hence we reccommend to use default values.

These goals run at the "generate-sources" Maven lifecycle phase.

By default, plugin scans Java source folders for annotated files ( src/main/java by default), src/main/templates folder for renderer templates and src/main/config for faces-config  XML files.

Generated Java sources are written to target/generated-sources/java folder and all non-java resources into target/generated-sources/resources folder. These places are registered in the maven build ass additional source and resource folders and processed by Maven in the next lifecycle phases. To run CDK goal this plugin should be defined in the <build> section:

  <build>
    <plugins>
      <plugin>
        <groupId>org.richfaces.cdk</groupId>
        <artifactId>maven-cdk-plugin</artifactId>
        <version>4.0.0-SNAPSHOT</version>
        <executions>
           <execution>
            <id>generate</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
....

Example of the project pom.xml is attached to the article, for more details see RichFaces 4.0.0.ALPHA1 CDK Tutorial