Usage Documentation

This file contains the usage documentation that is not directly related to the Java API. The JavaDoc is the best place for documentation on usage of the Java code.

Getting Started

Jar Manifest

The code uses the current thread class-path to scan for annotated files. Since this is not the fastest procedure, the code, by default, looks for attributes in the manifest files of the jars and class path entries.

For both directories, and jar files, it looks for a file path of META-INF/MANIFEST.MF. This file is loaded and scanned using the Java Manifest object. The named section net/sf/jsf-comp/facelets/deployment/ is looked for and the attributes Scan and RegisterPriority.

If the named section is not found or the Scan attribute is not set to true, the jar or directory will not be scanned.

Example manifest file:

Manifest-Version: 1.0

Name: net/sf/jsf-comp/facelets/deployment/
Scan: true
RegisterPriority: UNLESS_REGISTERED
Note: it is important that there is a new-line at the end of the file, or else
the last attribute will not be loaded by Java

The RegisterPriority key defines the default RegisterPriority enumeration value to be used if the annonation's registerWithFaces() enumeration property returns DEFAULT. If this attribute in the Manifest is not set, NONE will be used instead.

The reason for this functionality is to avoid having to set the registerWithFaces property on every annotation in a project. All annotations have a value of DEFAULT to begin with to allow this manifest value to be used.

Since the tag libraries are not loaded at the same time as the faces context being initialized, the UNLESS_REGISTERED value allows the annotated classes to be only registered with the Faces Application or RenderKit if they have not been already defined.

API

The next most important item to be familiarized with is the main API. The most important classes are:

  • DeploymentFinderFactory

    In order to provide for greater customizability, this factory builds the two factories that this project relies on.

    You can register factory classes with this finder any time before the parser is invoked (after the parser is invoked, there are no needs for the factories anymore).

  • FaceletAnnotationParser

    This class is the workhorse of the project. It is the one that navigates the class-path of the application, finding classes with the correct annotations.

Installation and Setup

As mentioned on the features page, there are multiple ways to deploy this functionality.

FaceletsViewHandler

The easiest way to deploy this functionality is to deploy the extended view handler. Benefits:

  • Configures the annotation tag libraries at the same time facelets deploys ones from taglib.xml files.
  • Gives the framework direct access to the Compiler instance that facelets uses to register the tag library instances.

Normal Registration

Add this to your faces-config.xml in the <application /> tag:

<view-handler>
  net.sf.jsfcomp.facelets.deploy.FaceletsViewHandler
</view-handler>

Registration with Ajax4Jsf

If you are using Ajax4Jsf, you need to put this definition in the web.xml and not the faces-config.xml. You can find information at the Ajax4Jsf site (please let me know if this link becomes dead since JBoss now controls the project):

https://ajax4jsf.dev.java.net/nonav/documentation/ajax-documentation/developerGuide.html#d0e2446

In case the link goes bad, here is the XML:

<context-param>
  <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
  <param-value>net.sf.jsfcomp.facelets.deploy.FaceletsViewHandler</param-value>
</context-param>

Manual Usage

Please check the JavaDoc information on the FaceletAnnotationParser class for details.