Chapter 4. Writing [fleXive] applications

Table of Contents

The [fleXive] distribution
Getting started
IDE integration
Eclipse
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
[fleXive] artifacts

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

  1. to use the [fleXive] distribution and utilize its Apache Ant build infrastructure, 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 grab a distribution package from the download page, unzip it to a local development directory, and create a new project from scratch. 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:

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

build.xml

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

applications

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

lib

Contains all [fleXive] libraries packaged as JAR files.

extlib

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.

templates

Contains project and component templates used by the build system.

META-INF

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 need a working environment including MySQL as described in the installation chapter.

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

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]
  [flexive] ear
  [flexive]     Create a flexive.ear distribution including any flexive application stored in
  [flexive]     flexive-dist/applications.
  [flexive]
  [flexive] glassfish.libs
  [flexive]     Copies libraries needed for Glassfish compatibility to a directory
  [flexive]
    [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:
project.create

check:

project.create:
    [input] Name of the project you want to create:
flexive-test
  [flexive]
  [flexive] Please confirm your input:
  [flexive] Project name:        flexive-test
  [flexive] Base directory:      ../flexive-test
  [flexive]
    [input] Are these settings correct? ([y], n)
y
    [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

BUILD SUCCESSFUL

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.

To deploy the application, first you need to setup the database schemas. Type ant db.create db.config.create and when prompted for the database schema use the default name, flexive. When the command completed successfully, your can deploy flexive-test.ear and have a working (albeit empty) [fleXive] application, including the backend administration application.

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:

src/java

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.

web

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

lib

contains additional libraries and components used by the project.

resources

is the root folder for various project resources:

resources/scripts

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

resources/messages

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

resources/META-INF

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

resources/templates

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.

We start with creating a new project for the flexive-test application directory.

  1. Open FileNew Project...

  2. Select Create project from scratch and press Next.

  3. Choose your [fleXive] project directory in Project file location.

  4. Click Next.

  5. Uncheck Create module and click Finish.

Let IDEA open the project. Next we add the template module file in the IDEA project settings dialog:

  1. Add a new module by clicking on the "+" button at the top of the screen.

  2. Choose Import existing module and select the IDEA module file (flexive-test.iml) in your project directory.

  3. Press Finish.

If this is your first IntelliJ IDEA project with [fleXive], please perform the following setup steps. Similar to Eclipse, we use a shared library definition to include [fleXive] in the project classpath.

  1. Open FileSettings

  2. Click on Project settings.

  3. On the left-hand-side, click on Platform settingsGlobal Libraries

  4. Add a new library by clicking on the "+" button at the top of the screen. Enter flexive-dist as the library name.

  5. Select your project module in the next screen and press OK.

  6. In the library overview screen, select the flexive-dist library and add the flexive-dist/applications, flexive-dist/lib and flexive-dist/extlib directories using the Attach JAR directories button.

Now you should have all [fleXive] classes available in your project. You can test this by opening the example EJB ( EJBExampleBean) using Go ToClass... ( Ctrl+N ) IDEA should not display any errors like missing classes.

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:

fxProject

The project name, in our example flexive-test.

flexive.dist.dir

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.

help

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

db.create

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

db.config.create

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