Lesson 1: Getting started

This lesson is the kick off to your first OpenXava application. After a brief revision of the application that we wish to develop, we shall configure all the tools that you need to develop an OpenXava application.
You are going to install Eclipse, configure Tomcat inside Eclipse and create the project for your application.
This lesson is used as an introduction to OpenXava and Eclipse. Keeping introduction in mind, this lesson is a little over explanatory, especially about the Eclipse IDE. So, if you are an already seasoned Eclipse user, just take a cursory look at this lesson, and go directly to the next lesson.

Our goal: A small invoicing application

The application chosen is a small invoicing application with invoices, customers, products and so on. This application is just a brief way to learn some typical cases in business applications. You can apply everything you learn with the invoicing application to any other business application of any other domain.
On the other hand, this invoicing application is a didactic tool. You are advised not to use it “as is” for a real invoicing system.

Creating the project in Eclipse

Undoubtedly Eclipse (alternatively NetBeans) is the ubiquitous IDE in the Java world. OpenXava comes out of the box ready to be used with Eclipse. You are going to develop your invoicing application using Eclipse. At the end of this chapter you'll have a first working version of your application developed as an Eclipse project.
This course assumes that you are using the “Eclipse IDE for Java EE Developers” edition of Eclipse with Java 11 or Java 8. The latest Eclipse version is fine, though you can use an older Eclipse version, until Eclipse Neon (4.6). If needed, get Eclipse from www.eclipse.org and Java from www.oracle.com.

Installing OpenXava

Go to www.openxava.org and download the latest OpenXava distribution. It is a zip file something like openxava-6.x.zip. Just uncompress it, and you will have an environment ready to start developing. Something like this:

As you see, OpenXava distribution includes Tomcat and an Eclipse workspace, all configured and ready to use. Let's start to work.

Create the project

Start your Eclipse and open the OpenXava workspace with it (File > Switch Workspace):

First, you have to create a new Java project:

Then a wizard will appear. Just type the project name, Invoicing, and click the Finish button:

Beware of writing the I of Invoicing in uppercase in order that the links below work correctly.

If you're using Java 9 or better with a recent version of Eclipse, it will ask you:

Just click on Don't Create.

After this step you have an empty Java project named Invoicing:

Now you must convert it into an OpenXava project:

Now you have to type the project name. Just type Invoicing and click OK. Wait a few second until it finishes, then you'll have a full OpenXava project there:

We are going to configure the Tomcat inside your Eclipse to use it as a platform for running your application.

Configuring Tomcat inside Eclipse

Starting Tomcat from Eclipse has several advantages such as you can debug, see the log messages and traces inside Eclipse, go from trace to code in a click, etc.
In the bottom part of Eclipse select the Servers tab and click on the link inside to create a new server:

A dialog will be shown, choose Apache Tomcat v9.0 (inside Apache folder) and click on Next:

Choose the Tomcat included with OpenXava as Tomcat installation directory and click on Next.

Finally, add your application to Tomcat and click on Finish:

Now the Tomcat is ready to be used.

Preparing the database

Your OpenXava application can go against any relational database, such as MySQL, PostgreSQL, Oracle, DB2, MS SQL Server and many many more. Moreover, you can change from a database to another without touching a single line of your code. For this course, we're going to use HSQLDB, because it's already included with OpenXava and very easy to configure. You can switch to your production database in any moment.

Creating the data source

A data source is the way an application server knows how to connect to a database. From our applications we only reference the data sources (and not the databases directly), so we have to configure the data sources in Tomcat to point to the correct databases. Let's define the data source for our Invoicing application.
Go to the Servers project of Eclipse, edit the file context.xml inside the folder of your server:

If you don't see the XML code of context.xml click on the Source tab. Then you have to add a new data source called InvoicingDS against your database. Just add the next code at the end of context.xml just before the last </Context> mark:

<Resource name="jdbc/InvoicingDS" auth="Container"
    type="javax.sql.DataSource"
    maxActive="20" maxIdle="5" maxWait="10000"
    username="sa" password=""
    driverClassName="org.hsqldb.jdbcDriver"
    url="jdbc:hsqldb:hsql://localhost:1666"/>

Starting database

To start your HSQLDB database with Windows click Start type cmd and press ENTER, then:

cd openxava-6.x\tomcat\bin
start-hsqldb invoicing-db 1666

With Linux/Mac:

cd openxava-6.x/tomcat/bin
./start-hsqldb.sh invocing-db 1666

You'll get an output like that:

You're database is already started and if it is the first time execution it has been created automatically.

Creating your first entity

At last you have your development environment configured. Now, developing the application is very easy. You only have to add entities in order to make your application grow. Let's create your first entity, and run the application.
First, you have to create the package to contain the model classes (the entities). Click right button on src in your project and choose New > Package:

In the dialog enter the package name, org.openxava.invoicing.model, and press Finish:

Instead of org.openxava you can use the domain of your organization. For example, if you work for the NASA you can named the package as gov.nasa.invoicing.model. You have learned how to create a Java package in Eclipse. From now on we won't use a figure for that.
Now, you can create your first entity. We start with a simple version of Customer with only number and description. Follow the next instructions to create a new Customer class:

Note that the C of Customer is uppercase, this is very important, all Java classes start by uppercase. You have learned how to create a Java class in Eclipse. From now on we won't use a figure for that.
The initial code that Eclipse provides for Customer is pretty simple:

package org.openxava.invoicing.model;
 
public class Customer {
 
}

Now, you have to fill this class in order to convert it to an entity suitable for OpenXava. You only need to add the @Entity annotation, the number and the description properties:

package org.openxava.invoicing.model;
 
import javax.persistence.*;
import org.openxava.annotations.*;
 
@Entity  // This marks Customer class as an entity
public class Customer {
 
    @Id  // The number property is the key property. Keys are required by default
    @Column(length=6)  // The column length is used at the UI level and the DB level
    private int number;
 
    @Column(length=50)  // The column length is used at the UI level and the DB level
    @Required  // A validation error will be shown if the name property is left empty
    private String name;
 
    public int getNumber() {
        return number;
    }
 
    public void setNumber(int number) {
        this.number = number;
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
}

At last you have enough code (just one class) to run your application. Let's run it.

Running the application

First, build your project clicking on the Build All button or pressing Ctrl-B:

Then to start your server go to the Servers view on bottom of Eclipse. If you don't see it, possibly you have maximized the current editor, just double click on the tab of the editor to minimize it and you'll see the complete Eclipse layout again.
Once there follow the next instructions:

Your application is already running. To check this, open your browser and go to the URL:
http://localhost:8080/Invoicing
You get your application running for the first time. To start click on SIGN IN button

Now, enter admin/admin and click on SIGN IN:

Then on top the left you will have a list of modules, choose Customers:

Use the Customers module to create new customers, just enter number and name and press Save.

Click on List to see the list of created customers. Congratulations, you have your environment configured and your application running.

Modifying the application

From now on, developing the application with OpenXava is very easy. Just write a class and go to your browser to see the result. Let's try it.
Create a new entity for Product with the next code:

package org.openxava.invoicing.model;
 
import javax.persistence.*;
import org.openxava.annotations.*;
 
@Entity
public class Product {
 
    @Id @Column(length=9)
    private int number;
 
    @Column(length=50) @Required
    private String description;
 
    public int getNumber() {
        return number;
    }
    public void setNumber(int number) {
        this.number = number;
    }
 
    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }
 
}

Now, press Ctrl-B. Most of the time is enough to press Ctrl-B to deploy automatically your code, but from time to time Eclipse fails to deploy and you have to restart Tomcat, fortunately restarting Tomcat takes only a few seconds. So, if your code is not deployed several seconds after Ctrl-B, just restart Tomcat with Right button on Tomcat > Restart.
To see your new entity in action open your browser and go to the URL:
http://localhost:8080/Invoicing/modules/Product
After sign in with admin/admin you'll get:

Yes, you have a new module running, and just writing a simple class. Now you can concentrate on growing your application.

Summary

After this lesson you have installed Eclipse and OpenXava. Moreover, you have configured everything in order to work. Now, you have your environment ready to develop your application.
Also, you have the very first version of your Invoicing application running.
But the most important thing is that you have learned how to create a new project, a new package, a new class, how to update the database schema, how to run an OpenXava module and other useful things that you will need to use in the rest of the course.
You're ready to continue to the next lesson, however you should consider to have a look at some base knowledge, such as:

If you're new to Java you should read an introductory Java book or read the Java Tutorial.
If you're interested in the philosophy and architecture of OpenXava read the appendix A of this course.
The appendices B and C about Java Persistence API and annotations will be very useful for you.

Download source code of this lesson

Any problem with this lesson? Ask in the forum Everything fine? Go to Lesson 2

Table of Contents