Table of Contents
There are two convenient ways to start a new [fleXive] project:
to use the [fleXive] distribution and create new projects with Apache Ant, or
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:
. |-- 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 administration GUI 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
JDK 6 or higher, and
Apache Ant 1.7.0 or higher.
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
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.
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:
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.
Please go to → → → →
Click
and enter
flexive
for the library name. Press
Select the created library entry, and press the button.
Go to your [fleXive] distribution directory, and select all JAR files
in the
lib/
folder (you can use shift-select here).
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.
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:
Open → + →
Select the project root directory.
Press Eclipse should now open the project in the workspace. To build the project EAR file using Ant, execute →
To check if the project and library has been loaded correctly, try to open
the
EJBExampleBean
class using
→ (
Shift+Ctrl+T
)
Eclipse should display the source code without errors.
We start with creating a new project for the
flexive-test
application directory.
Open →
Select and press
Choose your [fleXive] project directory in Project file location.
Click
Uncheck Create module and click
Let IDEA open the project. Next we add the template module file in the IDEA project settings dialog:
Add a new module by clicking on the "+" button at the top of the screen.
Choose
Import existing module
and select the IDEA module file
(flexive-test.iml) in your project directory.
Press Finish.
Please also note that if you want to work with the sources of the framework (not the distribution),
we provide a
flexive.ipr.sample
project sample file which you can copy to
flexive.ipr
and start coding and exploring right away.
The blank [fleXive] application includes an example EJB and JSF bean that shows the intended use of the package structure, cfe stands for com.flexive.example:
src/java/shared/cfe.shared.interfaces.EJBExample
Defines the (remote) interface of an EJB.
src/java/ejb/cfe.ejb.EJBExampleBean
Contains the EJB implementation of the
EJBExample
interface.
src/java/war/cfe.war.ManagedExampleBean
A sample implementation of a JSF wrapper bean that invokes
an EJB business method. Note the use of flexive's
EJBLookup
class to retrieve the EJB wrapper bean, since the
@EJB
annotation isn't supported by all application servers at the time
of this writing.
You can remove the example beans if you like, or rename them and use them as a start for your own beans (if any).
A [fleXive] application is a collection of JAR files that follow a few naming conventions
that will be packaged into an EAR archive. Note
that each file is optional, so if you for example don't provide EJB3 beans, you don't need
to provide a
-ejb.jar
file.
[basename]-ejb.jar
Contains the EJB3 implementations for your component.
[basename]-shared.jar
Contains shared classes of your application that are not tied to either the JSF or the EJB layer. This contains the EJB interface definitions, data transfer objects or general utility classes.
[basename].war
Contains the actual web application frontend, consisting of HTML pages, JSF components and Facelets templates, as well as JSF managed beans and deployment descriptors.
*.jar
Of course you can also package any additional JAR files containing
libraries or even JSF plugins. They will be stored in the
lib/
folder of the EAR file and will be available
to every [fleXive] application in the EAR file.
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.