Writing reusable [fleXive] components

Writing reusable [fleXive] components
Prev	Chapter 7. JSF Support	Next

While [fleXive] builds on existing JavaEE 5 infrastructure, it integrates additional services that make writing components for [fleXive] applications even easier.

Full EJB3 support in your applications and plugins, you can use existing EJBs or create new ones, and call your EJBs from [fleXive] via scripting.

Easy integration of JSF components and beans through JSF infrastructure, i.e. using a packaged faces-config.xml.

Serve Facelets templates directly from the JAR archive or any other location in the classpath.

Weblets can be used for serving content that is not handled by Facelets, like additional JavaScript files or stylesheets.
A compact plugin system allows to extend the administration GUI and make your own application or plugin extensible in a typesafe manner.
Setup your plugin or application using startup scripts that have full access to the [fleXive] API.

JSF components

JSF components provide a simple and powerful way of providing additional functionality to existing applications, for example a forum or comment section. A component packages all Java code and web resources into a single JAR file that can be dropped into the lib/ directory of an existing flexive.ear file. After the next [fleXive] startup it is available to all applications contained in the [fleXive] archive.

Build file support

The [fleXive] distribution contains a build target to create the directory structure of a standalone component, including a build file to compile and package the component.

To create a new component, open the command shell and go to the directory containing the [fleXive] distribution. Execute ant. You are greeted by the welcome screen of the flexive build tool. Enter component.create as the target name and supply the name of your component (e.g. test). When you confirm the input, a new component directory layout is initialized in the distribution's parent directory, in this case in ../test. Your screen should look approximately like this:

Buildfile: build.xml

info:
  [flexive]
  [flexive] Welcome to the flexive build tool. Feel free to use the following build targets:
  [flexive]
  [flexive] project.create
  [flexive]     Creates a new flexive project directory.
  [flexive]
  [flexive] component.create
  [flexive]     Creates a new flexive UI component directory.
  [flexive]
  [flexive] db.create
  [flexive]         Create or reset the database schema of a flexive division.
  [flexive]         Warning: if the schema already exists, it will be dropped (i.e. you will lose all data
  [flexive]         stored in the schema).
  [flexive]
  [flexive] db.config.create
  [flexive]         Create or reset the global flexive configuration schema.
  [flexive]
    [input] Please enter a target name, or quit to exit:
component.create

check:

component.create:
    [input] Name of the component you want to create:
test
  [flexive]
  [flexive] Please confirm your input:
  [flexive] Component name:      test
  [flexive] Base directory:      ../test
  [flexive]
    [input] Are these settings correct? ([y], n)
y
    [mkdir] Created dir: /tmp/test
     [copy] Copying 8 files to /tmp/test
     [copy] Copied 13 empty directories to 6 empty directories under /tmp/test
     [copy] Copying 1 file to /tmp/test
     [echo] Component test created successfully. The component root directory is
     [echo] ../test

Change to your component directory in ../test. The directory structure is similar to a [fleXive] project, the main difference is that there is only one source folder since all classes will be packaged into one JAR file.

.
|-- build.xml
|-- resources
|   |-- META-INF
|   |   |-- faces-config.xml
|   |   |-- flexive-plugins-config.xml
|   |   `-- weblets-config.xml
|   |-- messages
|   |-- scripts
|   |   |-- library
|   |   |-- runonce
|   |   `-- startup
|   |-- templates
|   `-- weblets
|-- src
|   `-- java
`-- web

src/java: contains the Java sources of the component.
web: contains the web documents of the component, e.g. configuration screens for the component.
resources/META-INF: contains the component's configuration files for JSF, the [fleXive] plugin descriptor, and the Weblets configuration.
resources/messages: contains the component's localized message resources that can be accessed with the fxMessageBean.
resources/scripts: contains the run-once, startup and library scripts of the component.
resources/weblets

To check if your build environment is working, execute ant in the component's base directory. An (empty) component JAR file should now be created in dist/test.jar. You can open the component in your favourite IDE now and start adding classes, templates and web pages. If you move the component directory to another directory (e.g. to maintain components in a larger [fleXive] project) be sure to modify the path to the [fleXive] distribution in build.xml.

Deployment

To deploy the component, you have to make it available to the [fleXive] application's classpath. The easiest way to do this is to add the JAR file to the lib/ folder of your flexive.ear file.

If you want to add it to your own [fleXive] project created by the build tool, you can copy it to the project's lib/ directory. When you build the EAR file, it will be added to the archive's lib/ folder and will be automatically deployed when [fleXive] starts up.

Packaging

A JSF component is a JAR file that may contain the following elements:

META-INF/faces-config.xml

Registers JSF beans, components, validators, and navigation rules. Note that you can reference XHTML pages from within your JAR file thanks to the classpath resource resolver as described in the section called “Delivering XHTML pages from the classpath”.

META-INF/*.taglib.xml

Register your own Facelets templates. The templates are stored directly in the JAR file and are referenced relative to the META-INF directory. For example, consider the following JAR contents:

./META-INF/mycomponents.taglib.xml
./templates/button.xhtml

To register your button tag, the mycomponents.taglib.xml might look like the following:

<?xml version="1.0"?>
<!DOCTYPE facelet-taglib PUBLIC
        "-//Sun Microsystems, Inc.//DTD Facelet Taglib 1.0//EN"
        "http://java.sun.com/dtd/facelet-taglib_1_0.dtd">

<facelet-taglib>
    <namespace>http://www.mycompany.com/jsf/components</namespace>

    <tag>
        <tag-name>button</tag-name>
        <source>../templates/button.xhtml</source>
    </tag>
</facelet-taglib>

Facelets scans the classpath for *.taglib.xml files and will automatically provide the registered templates and components under the given namespace.

META-INF/flexive-plugins-config.xml

Defines [fleXive] JSF plugins, as described in the section called “The JSF plugin API”.

META-INF/weblets-config.xml

Contains the Weblets configuration if you want to deliver additional web resources like images or stylesheets. The weblets resources are stored in the JAR file like Facelets templates, but their base directory may be any package in the JAR file. For example, the following config file sets the weblets root directory of the [fleXive] components package to com/flexive/faces/weblets and registers the weblet provider for the URI /flexive-web-resources/:

                                        <?xml version="1.0" encoding="UTF-8" ?>
<weblets-config xmlns="http://weblets.dev.java.net/config">
    <weblet>
        <weblet-name>com.flexive.faces.weblets</weblet-name>
        <weblet-class>
            net.java.dev.weblets.packaged.PackagedWeblet
        </weblet-class>
        <weblet-version>@FLEXIVE_VERSION@</weblet-version>
        <init-param>
            <param-name>package</param-name>
            <param-value>
                META-INF.resources.flexive-faces
            </param-value>
        </init-param>
    </weblet>
    <weblet-mapping>
        <weblet-name>com.flexive.faces.weblets</weblet-name>
        <url-pattern>/flexive-web-resources/*</url-pattern>
    </weblet-mapping>
</weblets-config>

If you attach -SNAPSHOT to the weblet-version number, you can disable browser caching for development builds. Otherwise Weblets will add caching information and you have to change the version number to ensure that all clients will use the most recent version.

EJB components

EJB3 components can be packaged in any JAR file and should be deployed automatically if included in the flexive.ear file. At the time of this writing, this mechanism was not working in current versions of Glassfish and JBoss unless you included an explicit ejb-ref.xml, so you have to add an explicit reference to the EJB JAR file in flexive.ear!/META-INF/application.xml if you use only EJB3 annotations. When you develop [fleXive] applications as described in Chapter 4, Writing [fleXive] applications , this is done automatically by the [fleXive] build system.

For further information on EJB packaging rules please refer to [Packaging EJB3 applications], which is also a chapter in the great [EJB3 in Action].

Writing reusable [fleXive] components