Chapter 4. Writing [fleXive] applications

Table of Contents

The [fleXive] distribution
Getting started
IDE integration
IntelliJ IDEA
Programming [fleXive]
Package for distribution
Build file support
Build targets
Building applications with Apache Maven
The [fleXive] Maven repository
Project archetypes
The EAR archetype
The WAR archetype
[fleXive] artifacts

There are two convenient ways to start a new [fleXive] project:

  1. to use the [fleXive] distribution and create new projects with Apache Ant, or

  2. to use Apache Maven and add [fleXive] to your project dependencies.

While 1) offers you out-of-the-box support for all [fleXive] features such as run-once scripts, plugins, weblet resources and so on, 2) is more modular and allows you to use [fleXive] just as any other library. Of course you can also use [fleXive] in your own enterprise application by adding the libraries.

The easiest way to get started with [fleXive] is to use the Java-based installer from the download page. The installation directory contains the [fleXive] distribution in the flexive-dist directory. In this chapter we will concentrate on creating new [fleXive] applications.

Looking at your local [fleXive] distribution directory, you will find the following directory layout:

|-- build.xml
|-- applications/
|-- extlib/
|-- lib/
|-- templates/


Contains the build file for creating new projects and components. To get started, simply execute ant in your flexive-dist/ directory.


Contains all [fleXive] applications that should be included in the EAR file. The standard distribution includes the administration GUI in this directory. To remove an application from the EAR, simply remove it from this directory and rebuild the EAR file.


Contains all [fleXive] libraries packaged as JAR files.


Contains all third-party libraries required for compiling and running [fleXive] applications. Note that not all libraries in this directory will be packaged into the final application archive, for example the JSF API package is only required for compiling JSF applications.


Contains project and component templates used by the build system.


Currently this directory only holds a template application descriptor for [fleXive] applications.

Before proceeding to create a new [fleXive] application, make sure you have a working build system, i.e. at least

For running the application you can use Jetty and the integrated H2 database if you used the installer. Otherwise, you have to configure an application server and a database according to Chapter 2, Installing [fleXive].

To get started with your first [fleXive] application, open a command shell and change to the directory containing the [fleXive] distribution. Type ant. You should be greeted by the welcome page of the [fleXive] build system:

Buildfile: build.xml

  [flexive] Welcome to the flexive build tool. Feel free to use the following build targets:
  [flexive] project.create
  [flexive]     Creates a new flexive project directory.
  [flexive] component.create
  [flexive]     Creates a new flexive UI component directory.
  [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] db.config.create
  [flexive]     Create or reset the global flexive configuration schema.
  [flexive] ear
  [flexive]     Create a flexive.ear distribution including any flexive application stored in
  [flexive]     flexive-dist/applications.
  [flexive] glassfish.libs
  [flexive]     Copies libraries needed for Glassfish compatibility to a directory
    [input] Please enter a target name, or quit to exit:

Let's create a new project. Type project.create and hit return. You will be asked for a project name. This name will be used as the root directory name for the project, so be careful to include only characters that may appear in filenames and URLs. For a start, enter flexive-test.

[fleXive] will create the project folder in the same directory where the [fleXive] distribution is stored, i.e. in the current parent directory. The major reason for this is that the project references the distribution directory, i.e. it includes all the libraries from the distribution directory and does not use its own copies. Thus new [fleXive] projects use little disk space, and you need only one [fleXive] distribution for all your projects.

After confirming your selection, the root directory layout for flexive-test will be created. Your screen should look approximately like this:

    [input] Please enter a target name, or quit to exit:


    [input] Name of the project you want to create:
  [flexive] Please confirm your input:
  [flexive] Project name:        flexive-test
  [flexive] Base directory:      ../flexive-test
    [input] Are these settings correct? ([y], n)
    [mkdir] Created dir: /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copying 4 files to /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copied 14 empty directories to 9 empty directories under /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copying 1 file to /home/daniel/dev/idea-workspace/flexive/flexive-test
     [copy] Copying 1 file to /home/daniel/dev/idea-workspace/flexive/flexive-test
     [echo] Project flexive-test created successfully. The project root directory is
     [echo] ../flexive-test


When the build tool has finished successfully, go to the newly created directory, e.g. cd ../flexive-test. The directory structure contains a blank project structure, which looks like the following:

|-- build.xml
|-- lib
|-- resources
|   |-- META-INF
|   |   |-- faces-config.xml
|   |   |-- template.taglib.xml.sample
|   |   `-- web.xml
|   |-- messages
|   |-- scripts
|   |   |-- library
|   |   |-- runonce
|   |   `-- startup
|   `-- templates
|-- src
|   `-- java
|       |-- ejb
|       |-- shared
|       `-- war
`-- web
    `-- index.xhtml

Before examining the directory structure, let's do a quick test if the the environment is working. Type ant. The build should complete successfully, leaving you with some artifacts in the dist/ subdirectory:

  • flexive-test.ear,

  • flexive-test-shared.jar, and

  • flexive-test.war.

If you used the installer, you can instantly boot the application with ant deploy.jetty run.jetty. If you didn't use the installer, or you want to reset the database schemas during development, type ant db.create db.config.create and when prompted for the database schema use the default name, flexive. After the command completes successfully, your can deploy flexive-test.ear to your application server and have a working (albeit empty) [fleXive] application, including the administration GUI.

The project root directory contains a build file, build.xml, that can be customized for the project. By default, it builds JAR files for all layers, including an EAR archive. The major subdirectories are:


contains the Java sources of the project. They are split up by layer, i.e. there are three distinct source trees for the EJB, web, and shared classes. This is especially useful for IDEs with support for multiple project modules, where you can also specify wanted (and forbidden) relationships between the layers.


contains the documents for the web application (if any).


contains additional libraries and components used by the project.


is the root folder for various project resources:


contains the run-once, startup and library scripts of the application,


contains the application's localized message resources that can be accessed with the fxMessageBean,


contains the application's configuration files, mostly for the web layer,


is the standard folder for Facelets templates. You can choose any folder of course if you like, but then you'd have to modify the build script.

Your [fleXive] project comes with basic project files for the Eclipse and IntelliJ IDEA Java IDEs.

If this is your first Eclipse project with [fleXive], first you have to define a new user library that includes the JAR files of your [fleXive] distribution. We also could include these files in the individual project classpath, but this way is much cleaner and easier to work with especially for multiple projects.

  1. Please go to WindowPreferencesJavaBuild PathUser Libraries.

  2. Click New... and enter flexive for the library name. Press OK.

  3. Select the created library entry, and press the Add JARs... button.

  4. Go to your [fleXive] distribution directory, and select all JAR files in the lib/ folder (you can use shift-select here).

  5. Repeat the last two steps and add all JAR files of the extlib/ folder and the flexive-plugin-jsf-core.jar from the applications/ folder to the user library.

  6. In the User Libraries page, click OK. You have now defined a global flexive library that includes all required JAR files for a [fleXive] application. Note that this is only available within the IDE, the actual build files do not use the IDE-specific library definitions.

Assuming that both your flexive-dist directory and the newly created project reside in your current Eclipse workspace directory, you can add the project following these steps:

  1. Open FileImport...+GeneralExisting Projects into Workspace

  2. Select the project root directory.

  3. Press Finish. Eclipse should now open the project in the workspace. To build the project EAR file using Ant, execute ProjectBuild all.

    To check if the project and library has been loaded correctly, try to open the EJBExampleBean class using NavigationOpen Type... ( Shift+Ctrl+T ) Eclipse should display the source code without errors.

If you created a new [fleXive] application with the tools of this chapter, it will include a buildfile for Apache Ant that compiles and packages the application into JAR and EAR files as described in the previous section. It uses a shared generic build file from the flexive-dist directory that is customized by setting a few Ant properties:


The project name, in our example flexive-test.


The [fleXive] distribution directory. By default this is a relative location. Keep this and do not alter the directory name if you want to keep the build environment independent from the actual workspace location.

[basename].shared.disabled , [basename].ejb.disabled , [basename].war.disabled , [basename].ear.disabled

If any of these properties is set, the corresponding archive file will not be generated. [basename] is the project name as set in the fxProject property, in our example application we would skip the EAR file generation using <property name="flexive-test.ear.disabled" value="1"/>.

The resulting JAR and EAR files will be stored in the dist/ directory of the project. If you deploy the EAR file into your application server, please make sure that no other [fleXive] EAR is deployed to prevent conflicts.

The default Apache Ant target builds the entire application, including an EAR file that can be deployed into your application server. Additional tasks are provided for setting up the database schemas.

package (default)

Build all archives, except disabled ones as described in the previous section.


Display a short help message and offer documentation of the most relevant tasks.


Create or reset a [fleXive] division database schema. By default, the first division uses the schema flexive.


Create or reset the global [fleXive] configuration schema, flexiveConfig.