CarRental – JFire Tutorial Part 1

Setup and first entity

March 22, 2011

Copyright (c) nightlabs. Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.3 or any
later version published by the Free Software Foundation; with no Invariant Sections, no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".

1
Contents
1. What the tutorial is about 3
1.1. General information for troubleshooting . . . . . . . . . . . . . . . . . . . 3
1.2. How this tutorial is structured . . . . . . . . . . . . . . . . . . . . . . . . 3

2. Development Environment Setup 4

2.1. Step 0.1: Java JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. Step 0.2: Eclipse SDK version 3.5 . . . . . . . . . . . . . . . . . . . . . . . 5
2.3. Step 0.3: Subclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4. Step 1: NightLabs SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5. Step 2: Initialise Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6. Step 3: Starting the JFire development server from within the IDE . . . . 8
2.7. Step 4: Starting the JFire development client from within the IDE . . . . 10

3. Create the new project 10

3.1. Including necessary libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2. Creating the class Car . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3. Getters and Setters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.4. Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.5. Making the object persistent . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.6. Fetch groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.7. Two basic methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.8. Creating CarID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.9. Storing the first cars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.10. Remote interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.11. Starting the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

A. GNU Free Documentation License 21

JFire Tutorial 2
1. What the tutorial is about

JFire has been around for more than six years with a growing community. As an free
open-source ERP-framework and high security product it has found many applications.
This tutorial now wants to give you a gentle introduction in less than two hours.
Our goal is to develop a small but fully functional car rental system using JFire. During
the step-by-step implementation we will describe the server- and client-side development
process. We will not only program this system, but also show you some best practices
that you can use for efficient programming with JFire.
The tutorial should also act as an anchor point for you if you are looking for some
specific information. Therefore we will sometimes give just a short introduction to some
commonly used techniques or other frameworks like JDO and give you some hints and
links where you can get more information.
This tutorial expects to have basic Java knowledge. Also it won’t hurt if you are familiar
with Eclipse already, although all steps will be explained in detail.
So lets start developing CarRental, the new open-source car rental system!

1.1. General information for troubleshooting

Here are some last information just in case you are running into some trouble later on.
In the Bugtracker bugs and other issues are listed. Since we will be using JFire-min
1.0, which has been stable for a long time, you hopefully won’t need it.
The most common question are of course answered in the FAQ. You might also take a
closer look at Development Troubleshooting or Server Installation Troubleshoot-
ing if you run into problems during this tutorial.
It is gernerally recommended to enable the “organize imports” feature of eclipse. To
enable this feature rightclick on your project and select “Properties” → “Save Actions”.
Then enable the checkbox “Enable project specific settings”, then “Perform the selected
action on save” and “Organize imports”.
The code we will programm in this first part of the tutorial is also avaible in the svn
repository. When you have problems with the code snippets listed in the text try to
download the project from our SVN repository, and compare your code with ours.

1.2. How this tutorial is structured

The goal of this tutorial is, to give an overview about how to begin a project using the
JFire-framework. We tried to explain every click you have to do, to give an overview
how to use JFire.
There are several colored boxes along the text to give several additional information.

JFire Tutorial 3
 These red boxes indicate common error sources.

These boxes give some tips to topics, not directly related to the JFire develop-
ment.

Additional information
These boxes contain additional information.

Here you can find information which are not directly “must knows” like conven-
tions, or what is a good programming style, which often make the life easier.

1 Source code is noted in boxes like this.

2. Development Environment Setup

We strongly recommend to use Eclipse as your IDE. Although the car rental system we
want to program could be done without it as well, Eclipse has some very nice features
that will help you to deploy JFire projects much faster. Therefore we start with some
preparing steps that maybe you can skip.
For our tutorial we use the following versions

Java SDK version 6

Eclipse SDK version 3.5
Subclipse: version 1.6
JFire: version 1.0

There are also some preconfigured JFire-Eclipse IDEs avaible for download.
If you install one these you may skip the steps 0 and 1.

2.1. Step 0.1: Java JDK

Download: Java JDK download

JFire requires Java 6.0. We recommend the JDK from Sun. If you have positive expe-
riences with another JDK, please feel free to post a message in the JFire Forum.

JFire Tutorial 4
2.2. Step 0.2: Eclipse SDK version 3.5

Download: Eclipse download

Download the latest Eclipse SDK 3.5 release from the Eclipse download page. We
recommend the “Eclipse IDE for Java EE Developers” package. Note that a 64-bit-
distribution of Eclipse requires a 64-bit-Java-JDK and a 32-bit-Eclipse needs 32-bit-Java.
Installation is very easy: Simply extract the archive and start ${installation-path}/Eclipse.exe
on Windows or ${installation-path}/Eclipse on other platforms.

Please use a new, empty workspace exclusively for JFire! If you re-use an
existing workspace, you might run into trouble.

Ensure that your default Installed JRE in Eclipse points to JDK 6. To verify
that, in Eclipse open Window > Preferences > Java > Installed JREs, check if
the Java 6 is selected as default.

It is a good idea to increase the JVMs memory limits and to enable garbage
collection of the “perm gen space” by adding/modifying these settings in your
eclipse.ini:

-Xmx1024m
-XX:+UseConcMarkSweepGC
-XX:+CMSClassUnloadingEnabled

Start Eclipse as soon as the installation has finished.

2.3. Step 0.3: Subclipse

subclipse update site

There are two common SVN plugins available for Eclipse: Subclipse and Subversive. In
our tutorial we will use Subclipse but feel free to use Subversive if you already know it.
So select “Help” → “Install New Software” from the menu. Before being able to download
subclipse you have to add the subclipse update site by simply clicking the “Add” button
on the top right. After confirming the following plug-ins should now be visible:

• Core SVNKit Library / SVNKit Library (required)

• Subclipse / Subclipse (required)

JFire Tutorial 5
 • Subclipse / SVNKit Client Adapter (not required)

So select the plug-ins and install them. After installing Eclipse will restart automatically.
Finally you have to set the right SVN interface. Select Window → Preferences -> Team
→ SVN and change the SVN interface from JavaHL to SVNKit.

2.4. Step 1: NightLabs SDK

Update site
Now that you have prepared your development environment you can start to install
JFire. Therefore we will install the nightlabs SDK from the update site as we did before
with sublipse.

Figure 1: installing the nightlabs SDK

2.5. Step 2: Initialise Workspace

After starting your SDK and closing the Welcome Intro, please choose in the main menu:
File → New → Other. . . → NightLabs → Workspace.
First you have to download the header-data by clicking on the “Load” button.
For detailed information about the “Initialise workspace” process please have a look at
this page: NightLabs SDK initialise workspace wizard

JFire Tutorial 6
 Figure 2: screenshot of the workspace setup

Figure 3: screenshot of the workspace initialisation

JFire Tutorial 7
 The Initialize Workspace process should configure Eclipse as needed for JFire develop-
ment. In the case that file encoding and target platform settings are wrong, see the
Eclipse configuration page.

JFire-Versions
For the tutorial we will use JFire_Min 1.0 as a base. As you may see during
the initialisation process there are several different versions avaible. Apart from
the the different version numbers you can see, that there is a Max and a Min
version.

JFire_Min JFire_Min is just the product JFire with its basic libraries and
frameworks. Since you won’t have to cope with much dependencies it is
a good starting point for our tutorial.

JFire_Max JFire_Max already has many projects that may probably be very
useful if you develop your own projects later on.

2.6. Step 3: Starting the JFire development server from within the IDE

Now that the work space is created you have to setup and configure the server.
The initialization process automatically creates a launch configuration for the server,
but currently it has to be change in order for the server to work correctly. Go to the
‘Servers’ view, double-click your server, click on “Open launch configuration” and adjust
the “VM arguments” in the “Arguments” tab.
Add the following line. Without this setting the server will start with a NullPointerEx-
ception and all Jbpm workflows will not work.
1 −javaagent:../server/default/deploy/jboss−aop−jdk50.deployer/pluggable−
instrumentor.jar

You can now start the server for set-up and configuration. Don’t be confused if some
errors pop-up in the console view. These can be safely ignored right now until the server
is configured.
Open the “Servers” view. Select the “JFire-JBoss” entry, rightclick on it and select “Add
and Remove. . . ”.
The menu for adding and removing projects to the server will open. Now just click the
button “Add All >>”, because some other projects are also needed to run the server
correctly.
Afterwards click “Finish” to apply the changes. Now you have to publish the projects.
Again rightclick on the server and select “Publish”. Now all the projects are packed into
*.jar files to provide them to the server. Now click the start button. The server will
start up and will automatically shut down a few seconds later.

JFire Tutorial 8
Figure 4: the menuitem “Add and Remove”

Figure 5: the menu “Add and Remove”

JFire Tutorial 9
Now we can start the server again. As soon as the server is running (the server view has
to state “started” and the console view must mention “JFireServer is up and running”)
you may go to http://localhost:8080/JFireWebAdmin. Congratulations, you have
a functional server running!
For details about server configuration see ServerInstallation. While configuring you
must create an organisation with one user and his password. For some further steps in
part two of the tutorial you can create an organisation named “test.jfire.org” with a user
“admin” and the password “admin”. But you can also create this organisation later.

2.7. Step 4: Starting the JFire development client from within the IDE

Open Run → Run Configurations. . . Under “Eclipse Application” you will find an entry
“JFire”. Select it and click the “Run” button. A JFire client will now start. Of course
it is empty at the moment, since our car rental system still has to be developed.

If your initialization failed and you double checked to have followed all the steps
mentioned on this page, take a look at the Development Troubleshooting
page or the forum and contact us if you still haven’t found an answer.

3. Create the new project

Now that we have installed and configured all necessary software we can start to develop
our project. Since a car-rental system will at the very least need some information about
the cars that can be rented we will start by creating an object Car that should be later
stored in the database.
At the beginning of every JFire-project you have to create a Enterprise Java Beans
(EJB) project.

All the projects implementing a serverside project are named in camelcase start-
ing with JFire so we name our project JFireCarRental. Of course it’s just a
naming convention but since in later projects you probably want to include a
lot of other projects the camelcase-notation helps to keep track of them and
you don’t have to reinvent the wheel to create a new notation for this common
problem.
See the wiki for further information about project naming conventions.

So let’s press ctrl+n now and select EJB-Project. In the wizard you can now enter the
projectname. You should also check the Add project to an EAR box since it will be later
used by the server. The EAR-projects should have the same name as the projects they
belong to with an appended suffix “EAR” as the wizard probably already has proposed.
The other presets should be ok, so you can press Finish now.

JFire Tutorial 10
 Figure 6: create an EJB-project

3.1. Including necessary libraries

Since we have (at minimum) to use the libraries of JDO1 we now have to add the
corresponding libraries to the build-path of our project. Therefore we right-click on
the project JFireCarRental in our project-explorer, choose properties and select “JDO
Project Settings” in the menu on the left. There we check the options “Enable JDO
Classpath Container” and “Enable JDO Enhancer Builder”.

3.2. Creating the class Car

In this step we want to create a simple model of a car and persist it into a database.
Within the JFireCarRental project you created in the last step you should now first
create a package named org.nightlabs.jfire.car2 . Finally you have to add a class
called Car in the source folder: JFireCarRental/src. The class must implement the
interface Serializable.
public class Car implements Serializable {
2
private static final long serialVersionUID = 1L;

1
Java Database Objects (JDO) is used for storing objects and making the process of storing independent
of the used database system in the background. Therefore your could use e.g. MySQL, SQlite or
even non-relational databases. For more information about JDO in general visit the Java website
for JDO. In our tutorial we will just cover the most important aspects.
2
We use the naming convention of JFire: org.nightlabs.{project}.{subproject}[.ui].{logic compo-
nent}[.{logic subcomponent}.*]. For more information take a look at the coding conventions
in the wiki.

JFire Tutorial 11
 4
private long carID;
6
protected String brand;
8
protected String color;
10
protected String model;
12
protected byte[] picture;
14
...
16 }

As you can see, our basic car model is really simple. Since we want to create an unique
key to every car-object which can appear in the database we use a composite key, con-
sisting of the organisationID of the organisation the car belongs to and a carID. The
organisationID has the type String and the carID the type long.
Apart from these basic and always needed informations about the object we added the
attributes brand, model and color, all three of type String. We also defined the attribute
picture as a byte array.
Later on you probably want to extend this model. How about a picture of the car for
example? But for now our model will suffice.

3.3. Getters and Setters

Although we will first need them in the second part of the tutorial we now create the
getters and setters for the attributes of our car object, as usual in object oriented pro-
gramming. Here is an example for the brand-attribute, the other variables are handled
in the same way.
public void setBrand(String brand) {
2 this.brand = brand;
}
4
public String getBrand() {
6 return brand;
}

3.4. Constructor

After the creation of the setters and getters we now have to write the constructor for
our class. In the constructor we take a parameter of type CarID. So we can pass an
instance of a car with a specific ID, or pass null to instantiate a Car with a new unique
ID, created using the IDGenerator. With JFire we can create this class CarID without
much effort - the process of creating this class will be explained later.
1 public Car(CarID carID) {
this.organisationID = carID == null ?

JFire Tutorial 12
 3 IDGenerator.getOrganisationID() : carID.organisationID;
this.carID = carID == null ?
5 IDGenerator.nextID(Car.class) : carID.carID;
}

The IDGenerator is a class of JFire that generates a set of unique IDs. If we pass
null calling to this constructor it will retrieve the organisationID by itself by using the
current users organisationID and generate a unique carID for it.

3.5. Making the object persistent

To provide the information to JDO on how our Car class should be treated we use
JDO-annotations.
@PersistenceCapable(
2 objectIdClass=CarID.class,
identityType=IdentityType.APPLICATION,
4 detachable="true",
table="JFireCar_Car")
6 public class Car {
...
8 }

As you can see we used CarID again. This class defines the identity of a Car instance
and implements the JDO specification of id-objects.
Now we tell JDO how to handle each attribute of our Car.
1 public class Car implements Serializable{

3 @PrimaryKey
@Column(length=100)
5 private String organisationID;

7 @PrimaryKey
private long carID;
9
private String brand;
11
private String model;
13
private String color;
15
@Persistent
17 protected byte[] picture;

19 ...
}

So what are the annotations we used for:

@PrimaryKey The primary key option marks the attribute as belonging to the primary
key. JDO uses this information for creating a primary key in the database.
@Column Column tells the database the properties of the attribute. We have to set it
for the organisationID because we want to restrict the allocated space for this key
in the database.

JFire Tutorial 13
 It is a good idea to include the organisationID in the primary key so you can
later on share your objects more easily between the organisations.

3.6. Fetch groups

Fetch groups are a way to retrieve data from the database through JDO. For more
information of FetchGroups you can visit the DataNucleus site about them.
@FetchGroups({
2 @FetchGroup(
name="Car.picture",
4 members=@Persistent(name="picture")
)
6 })
public class Car implements Serializable{
8 ...
}

The “default” fetch group comprises all fields of the following types:

• primitives : boolean, byte, char, double, float, int, long, short

• object wrappers of primitives : Boolean, Byte, Character, Double, Float, Integer,
Long, Short
• java.lang.String, java.lang.Number
• java.math.BigDecimal, java.math.BigInteger
• java.util.Date

Since our String attributes are already included in our default fetch group we don’t
need to specify fetch groups for them.3 But the picture attribute of the Car instance
is a byte array, which won’t be loaded by default, therefore we have to define the fetch
group above to access the data for the picture of the car. Loading the picture by default
wouldn’t make much sense, anyway. If we just want to display our stored cars in a list
we probably wouldn’t make use of the pictures and therefore much unnecessary data
would be loaded.
The code above would work. But since JFire is often used in large projects we at
NightLabs use a slightly expanded way of declaring the fetch groups as shown below.
1 @FetchGroups({
@FetchGroup(
3 name="Car.picture",
members=@Persistent(name="Car.FieldName.picture")
5 )
})
7 public class Car implements Serializable{

3
If we really didn’t want to load other attributes we could define fetch groups to just load the required
ones. But since accessing and transferring the types specified in “default” is really fast, we at normally
don’t need such optimisation.

JFire Tutorial 14
 9 public static final class FieldName {
public static final String picture = "picture";
11 }

13 private static final String fetchGroupPrefix = "Car.";

15 public static final String FETCH_GROUP_PICTURE =

fetchGroupPrefix + FieldName.picture;
17
...
19 }

This way of defining fetch groups allows for easier identification and autocompletion
within the IDE. Using this convention allows later on to access our fetch group for the
picture attribute by referring to FETCH_GROUP_PICTURE.
So lets describe this convention a little bit:

1. First create an inner class FieldName.

2. Add the attributes as public, static and final, so they can be excessed from other
classes. This is necessary, since we want to identify the fetch groups by these
Strings later on.
3. Create a “fetchGroupPrefix” using the name of the class.
4. Create “FETCH_GROUP_XZY” for the attributes.
5. Create the annotation FetchGroups. Although in our case the model is really simple
and we need just one fetch group and therefore we could omit the annotation it is
recommend to use it for unifying the code layout and for later expansions of the
model.
6. Create one FetchGroup for all required attributes inside “FetchGroups”
7. set a name for each FetchGroup by using the defined constants
8. set the members of every FetchGroup to their corresponding value and make them
persistent

3.7. Two basic methods

The Methods equals and hashCode should always be implemented to ensure a correct
behaviour of the JFire framework.
1 public int hashCode() {
return (31 ∗ Util.hashCode(organisationID)) + Util.hashCode(carID);
3 }

5 public boolean equals(Object obj) {

if (this == obj) return true;
7 if (obj == null) return false;
if (getClass() != obj.getClass()) return false;
9

JFire Tutorial 15
 Car other = (Car) obj;
11 return Util.equals(other.organisationID, this.organisationID) &&
Util.equals(other.carID, this.carID);
13 }

The equals method checks if a given object is equal to this one. It uses the primary key
fields of the object (in our case organisationID and carID) since they are unique to an
entity.
The primary key fields are also used for generating the hashCode.
This way, the concept of equality is the same for the Java virtual machine and the
database server. In other words, the behaviour of objects being loaded into memory and
their persistent counterparts (e.g. accessed via SQL) is exactly the same, preventing
unpredictable, cache-dependent behaviour of the JDO implementation.
Additionally, primary-key-based equality is useful for managing detached instances on
the client-side, as - for example - a new version of an object would replace the old one
in a Set.

It is also recommended to write a toString method, which will be used by the

debugger as well as loggers to get more useful information.

3.8. Creating CarID

As we mentioned before we have to create a class CarID for the identification of the
objects. Luckily the NightLabs SDK does this tedious process on its own. By right-
clicking on our Car-class and selecting New and choosing Other → Nightlabs → JDO
Object-id class we get a dialog for creating the ID-class.
To conform with the JFire-convention of id-objects we have to add the interface ObjectID
by clicking add to the class as shown in the screenshot.

3.9. Storing the first cars

Now we are nearly finished with the first part of the tutorial. The last step left is the
process of storing some cars to our database. To do this we now shortly introduce two
additional classes that will be further explained in Tutorial Part 2, in the chapter the
bean and the access via interface.
The process of creating the two classes is in our case actually really simple. Right click
on the project in the project tree and select Properties → Java Build Path → Projects.
JFireBaseBean is a base class with many helpful functionalities that we will need. To
use it choose Add and select the project JFireBaseBean and confirm it by clicking two
times on “Ok”.

JFire Tutorial 16
 Figure 7: Settings for the creation of the ID-class.

Now right click on the package org.nightlabs.jfire.carrental and select New → Other
and then EJB → Session Bean. Press the Next button and type in the class name Car-
RentalBean. The superclass of the bean is the

org.nightlabs.jfire.base.BaseSessionBeanImpl

Click Browse, select this class and click OK. The state type of the bean is stateless, which
should be set by default. Check remote and uncheck local, because we do not need a
local interface so far. Change the name of the remote interface to CarRentalRemote.
Now we can proceed with Next. On the next page the default setting should be ok (see
figure “The bean, part 2”), and you just have to press Finish.

3.10. Remote interface

There is not much to define in this class at the moment, since our goal is just to store
some objects and so a simple initialise method will be sufficient.
1 @Remote
public interface CarRentalRemote {
3 void initialise() throws Exception;
}

Here again we use an annotation as we did before in the “making the object persistent”
section. In the code above the @Remote annotation simply declares this interface as a
remote one.

JFire Tutorial 17
Figure 8: The bean, part 1.

Figure 9: The bean, part 2.

JFire Tutorial 18
 The method initialise won’t be explicitly called by us. But internally initialise is used
to make some first needed data persistent.

Bean implementation The class BaseSessionBeanImpl, which usage we already ex-

plained above, belongs to the project org.nightlabs.jfire.base and controls the ses-
sions which means that we don’t have to handle them manually. Create a new class,
named CarRentalBean, which extends BaseSessionBeanImpl. Because we have to im-
plement the initialise method defined in the CarManagerRemote interface we now write
these implementations:
@Stateless
2 public class CarRentalBean
extends BaseSessionBeanImpl
4 implements CarRentalRemote
{
6 private static final long serialVersionUID = 1L;

8 @RolesAllowed("_System_")
@Override
10 public void initialise() throws Exception {

12 PersistenceManager pm = this.createPersistenceManager();

14 try {
ModuleMetaData moduleMetaData = ModuleMetaData.getModuleMetaData(pm,
16 CarRentalEAR.MODULE_NAME);

18 if (moduleMetaData == null) {
moduleMetaData = ModuleMetaData.createModuleMetaDataFromManifest
20 (CarRentalEAR.MODULE_NAME, CarRentalBean.class);
moduleMetaData = pm.makePersistent(moduleMetaData);
22 }

24 Car car1 = new Car(null);

car1.setColor("black");
26 car1.setBrand("BMW");
car1.setModel("3er");
28
Car car2 = new Car(null);
30 car2.setColor("yellow");
car2.setBrand("VW");
32 car2.setModel("Polo");

34 Car car3 = new Car(null);

car3.setColor("Silver");
36 car3.setBrand("Audi");
car3.setModel("TT");
38
pm.makePersistent(car1);
40 pm.makePersistent(car2);
pm.makePersistent(car3);
42 }
finally {
44 pm.close();
}
46 }

JFire Tutorial 19
 We didn’t include the attribute picture for our cars at this point since it would
have made the code much less simple and we won’t use it anyway for the demon-
stration in the next part of this tutorial.
In Tutorial Part 3 you will learn to create a wizard for adding cars and use a
file dialog for selecting a picture.

PersistenceManger The PersistenceManager, wqe have used in the initialise method,

is the key to all persistence operations in JDO. With it you can persist, update, delete,
and retrieve objects from the datastore.

jboss.xml Finally you should create the file jboss.xml in the META-INF folder with
the following content:
<?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS 4.2//EN"
"http://www.jboss.org/j2ee/dtd/jboss_4_2.dtd">
4 <jboss>
<security−domain>java:/jaas/jfire</security−domain>
6 </jboss>

We will explain the details of this file in a later part of the tutorial in context. For now
it should suffice to know that you will need this simple code snippet for the security
authentication (e.g. between server and client).

3.11. Starting the Project

Our project is now ready to get launched for the first time. Add the CarRentalEAR to
the server, and puplish it (chapter 1.2.7). If you now start the server the cars will be
persisted to the database. You can look in the MySQL/Derby Database and you will
find it there.

The code we programmed in this first part of the tutorial is also available in
the svn repository.

JFire Tutorial 20
A. GNU Free Documentation
License
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foun-
dation, Inc. Everyone is permitted to copy and distribute ver-
batim copies of this license document, but changing it is not
allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or
other functional and useful document “free” in the sense of free-
dom: to assure everyone the effective freedom to copy and redis-
tribute it, with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the au-
thor and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative
works of the document must themselves be free in the same
sense. It complements the GNU General Public License, which
is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same free-
doms that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regard-
less of subject matter or whether it is published as a printed
book. We recommend this License principally for works whose
purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it
can be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The “Doc-
ument”, below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as “you”. You accept
the license if you copy, modify or distribute the work in a way
requiring permission under copyright law.
A “Modified Version” of the Document means any work contain-
ing the Document or a portion of it, either copied verbatim, or
with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter
section of the Document that deals exclusively with the relation-
ship of the publishers or authors of the Document to the Docu-
ment’s overall subject (or to related matters) and contains noth-
ing that could fall directly within that overall subject. (Thus, if
the Document is in part a textbook of mathematics, a Secondary
Section may not explain any mathematics.) The relationship
could be a matter of historical connection with the subject or
with related matters, or of legal, commercial, philosophical, eth-
ical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in the
notice that says that the Document is released under this Li-
cense. If a section does not fit the above definition of Secondary
then it is not allowed to be designated as Invariant. The Doc-
ument may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover
Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable
copy, represented in a format whose specification is available to
the general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images com-
posed of pixels) generic paint programs or (for drawings) some
widely available drawing editor, and that is suitable for input
to text formatters or for automatic translation to a variety of
formats suitable for input to text formatters. A copy made in an
otherwise Transparent file format whose markup, or absence of
JFire Tutorial
markup, has been arranged to thwart or discourage subsequent
modification by readers is not Transparent. An image format is
not Transparent if used for any substantial amount of text. A
copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input for-
mat, SGML or XML using a publicly available DTD, and standard-
conforming simple HTML, PostScript or PDF designed for hu-
man modification. Examples of transparent image formats in-
clude PNG, XCF and JPG. Opaque formats include proprietary
formats that can be read and edited only by proprietary word
processors, SGML or XML for which the DTD and/or process-
ing tools are not generally available, and the machine-generated
HTML, PostScript or PDF produced by some word processors
for output purposes only.
The “Title Page” means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, “Title
Page” means the text near the most prominent appearance of the
work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes
copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Doc-
ument whose title either is precisely XYZ or contains XYZ in
parentheses following text that translates XYZ in another lan-
guage. (Here XYZ stands for a specific section name mentioned
below, such as “Acknowledgements”, “Dedications”, “Endorse-
ments”, or “History”.) To “Preserve the Title” of such a section
when you modify the Document means that it remains a section
“Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the
notice which states that this License applies to the Document.
These Warranty Disclaimers are considered to be included by
reference in this License, but only as regards disclaiming war-
ranties: any other implication that these Warranty Disclaimers
may have is void and has no effect on the meaning of this Li-
cense.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium,
either commercially or noncommercially, provided that this Li-
cense, the copyright notices, and the license notice saying this
License applies to the Document are reproduced in all copies,
and that you add no other conditions whatsoever to those of
this License. You may not use technical measures to obstruct or
control the reading or further copying of the copies you make or
distribute. However, you may accept compensation in exchange
for copies. If you distribute a large enough number of copies you
must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated
above, and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than
100, and the Document’s license notice requires Cover Texts,
you must enclose the copies in covers that carry, clearly and
legibly, all these Cover Texts: Front-Cover Texts on the front
cover, and Back-Cover Texts on the back cover. Both covers
must also clearly and legibly identify you as the publisher of
these copies. The front cover must present the full title with
all words of the title equally prominent and visible. You may
add other material on the covers in addition. Copying with
changes limited to the covers, as long as they preserve the title
of the Document and satisfy these conditions, can be treated as
verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit rea-
sonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a machine-
readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a computer-network loca-
tion from which the general network-using public has access to
21
download using public-standard network protocols a complete
Transparent copy of the Document, free of added material. If
you use the latter option, you must take reasonably prudent
steps, when you begin distribution of Opaque copies in quantity,
to ensure that this Transparent copy will remain thus accessible
at the stated location until at least one year after the last time
you distribute an Opaque copy (directly or through your agents
or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors
of the Document well before redistributing any large number of
copies, to give them a chance to provide you with an updated
version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Docu-
ment under the conditions of sections 2 and 3 above, provided
that you release the Modified Version under precisely this Li-
cense, with the Modified Version filling the role of the Document,
thus licensing distribution and modification of the Modified Ver-
sion to whoever possesses a copy of it. In addition, you must do
these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title dis-
tinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the His-
tory section of the Document). You may use the same title as
a previous version if the original publisher of that version gives
permission. B. List on the Title Page, as authors, one or more
persons or entities responsible for authorship of the modifica-
tions in the Modified Version, together with at least five of the
principal authors of the Document (all of its principal authors, if
it has fewer than five), unless they release you from this require-
ment. C. State on the Title page the name of the publisher of
the Modified Version, as the publisher. D. Preserve all the copy-
right notices of the Document. E. Add an appropriate copyright
notice for your modifications adjacent to the other copyright
notices. F. Include, immediately after the copyright notices, a
license notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below. G. Preserve in that license notice the
full lists of Invariant Sections and required Cover Texts given in
the Document’s license notice. H. Include an unaltered copy of
this License. I. Preserve the section Entitled “History”, Preserve
its Title, and add to it an item stating at least the title, year,
new authors, and publisher of the Modified Version as given on
the Title Page. If there is no section Entitled “History” in the
Document, create one stating the title, year, authors, and pub-
lisher of the Document as given on its Title Page, then add an
item describing the Modified Version as stated in the previous
sentence. J. Preserve the network location, if any, given in the
Document for public access to a Transparent copy of the Docu-
ment, and likewise the network locations given in the Document
for previous versions it was based on. These may be placed in
the “History” section. You may omit a network location for a
work that was published at least four years before the Document
itself, or if the original publisher of the version it refers to gives
permission. K. For any section Entitled “Acknowledgements” or
“Dedications”, Preserve the Title of the section, and preserve
in the section all the substance and tone of each of the con-
tributor acknowledgements and/or dedications given therein. L.
Preserve all the Invariant Sections of the Document, unaltered
in their text and in their titles. Section numbers or the equiva-
lent are not considered part of the section titles. M. Delete any
section Entitled “Endorsements”. Such a section may not be in-
cluded in the Modified Version. N. Do not retitle any existing
section to be Entitled “Endorsements” or to conflict in title with
any Invariant Section. O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version’s license notice. These titles must be distinct from any
other section titles.
You may add a section Entitled “Endorsements”, provided it
contains nothing but endorsements of your Modified Version by
various parties—for example, statements of peer review or that
the text has been approved by an organization as the authori-
tative definition of a standard.
You may add a passage of up to five words as a Front-Cover
Text, and a passage of up to 25 words as a Back-Cover Text, to
JFire Tutorial
the end of the list of Cover Texts in the Modified Version. Only
one passage of Front-Cover Text and one of Back-Cover Text
may be added by (or through arrangements made by) any one
entity. If the Document already includes a cover text for the
same cover, previously added by you or by arrangement made
by the same entity you are acting on behalf of, you may not add
another; but you may replace the old one, on explicit permission
from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or
to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released
under this License, under the terms defined in section 4 above
for modified versions, provided that you include in the combina-
tion all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your com-
bined work in its license notice, and that you preserve all their
Warranty Disclaimers.
The combined work need only contain one copy of this License,
and multiple identical Invariant Sections may be replaced with
a single copy. If there are multiple Invariant Sections with the
same name but different contents, make the title of each such
section unique by adding at the end of it, in parentheses, the
name of the original author or publisher of that section if known,
or else a unique number. Make the same adjustment to the
section titles in the list of Invariant Sections in the license notice
of the combined work.
In the combination, you must combine any sections Entitled
“History” in the various original documents, forming one sec-
tion Entitled “History”; likewise combine any sections Entitled
“Acknowledgements”, and any sections Entitled “Dedications”.
You must delete all sections Entitled “Endorsements”.
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individ-
ual copies of this License in the various documents with a single
copy that is included in the collection, provided that you fol-
low the rules of this License for verbatim copying of each of the
documents in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of
that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume
of a storage or distribution medium, is called an “aggregate”
if the copyright resulting from the compilation is not used to
limit the legal rights of the compilation’s users beyond what the
individual works permit. When the Document is included in
an aggregate, this License does not apply to the other works in
the aggregate which are not themselves derivative works of the
Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one
half of the entire aggregate, the Document’s Cover Texts may
be placed on covers that bracket the Document within the ag-
gregate, or the electronic equivalent of covers if the Document
is in electronic form. Otherwise they must appear on printed
covers that bracket the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of sec-
tion 4. Replacing Invariant Sections with translations requires
special permission from their copyright holders, but you may in-
clude translations of some or all Invariant Sections in addition
to the original versions of these Invariant Sections. You may
include a translation of this License, and all the license notices
in the Document, and any Warranty Disclaimers, provided that
you also include the original English version of this License and
the original versions of those notices and disclaimers. In case of
22
a disagreement between the translation and the original version
of this License or a notice or disclaimer, the original version will
prevail.

If a section in the Document is Entitled “Acknowledgements”,

“Dedications”, or “History”, the requirement (section 4) to Pre-
serve its Title (section 1) will typically require changing the
actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Doc-

ument except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, or distribute it
is void, and will automatically terminate your rights under this
License.

However, if you cease all violation of this License, then your

license from a particular copyright holder is reinstated (a) pro-
visionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copy-
right holder fails to notify you of the violation by some reason-
able means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is re-

instated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you
have received notice of violation of this License (for any work)
from that copyright holder, and you cure the violation prior to
30 days after your receipt of the notice.

Termination of your rights under this section does not terminate

the licenses of parties who have received copies or rights from
you under this License. If your rights have been terminated and
not permanently reinstated, receipt of a copy of some or all of
the same material does not give you any rights to use it.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised ver-

sions of the GNU Free Documentation License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version

number. If the Document specifies that a particular numbered
version of this License “or any later version” applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been pub-
lished (not as a draft) by the Free Software Foundation. If the
Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by
the Free Software Foundation. If the Document specifies that
a proxy can decide which future versions of this License can be
used, that proxy’s public statement of acceptance of a version
permanently authorizes you to choose that version for the Doc-
ument.

11. RELICENSING

“Massive Multiauthor Collaboration Site” (or “MMC Site”) means

any World Wide Web server that publishes copyrightable works
and also provides prominent facilities for anybody to edit those
works. A public wiki that anybody can edit is an example
of such a server. A “Massive Multiauthor Collaboration” (or
“MMC”) contained in the site means any set of copyrightable
works thus published on the MMC site.

“CC-BY-SA” means the Creative Commons Attribution-Share

Alike 3.0 license published by Creative Commons Corporation,
a not-for-profit corporation with a principal place of business in
San Francisco, California, as well as future copyleft versions of
that license published by that same organization.

“Incorporate” means to publish or republish a Document, in

whole or in part, as part of another Document.

An MMC is “eligible for relicensing” if it is licensed under this

License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently in-
corporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.

The operator of an MMC Site may republish an MMC contained

in the site under CC-BY-SA on the same site at any time before
August 1, 2009, provided the MMC is eligible for relicensing.

JFire Tutorial 23