Table of Contents

Lesson 1: Getting started
Our goal: A small invoicing application
Installing needed software
Install Java
Install Eclipse
Install OpenXava
Creating the project in Eclipse
Creating your first entity
Running the application
Modifying the application
Summary
Course: 1. Getting started | 2. Modeling with Java | 3. Automated testing | 4. Inheritance | 5. Basic business logic | 6. Advanced validation | 7. Refining the standard behavior | 8. Behavior & business logic | 9. References & collections | A. Architecture & philosophy | B. Java Persistence API | C. Annotations

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 Java and Eclipse, and create the project for your application.

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.

Installing needed Software

Install Java

If you already have JDK 8 or 11 in your machine skip this step
Go to Oracle JDK 11 download page:
Choose the installer for your operating system, download it, run it and follow all the steps to install the JDK in your computer.
If you have a 32 bits machine, you should download and install JDK 8 instead, go to JDK 8 download page and choose a 32 bits (i586) version.

Install Eclipse

If you already have Eclipse (any version) in your machine skip this step
Eclipse is a popular IDE in the Java world. OpenXava comes out of the box ready to be used with Eclipse (though IntelliJ IDEA is also supported). You are going to develop your invoicing application using Eclipse.
Go to Eclipse download page:
Click on the orange 64 bit link corresponding to your operating system to download the installer. Run it, it will show the following options:
Choose the first one, Eclipse IDE for Java Developers, and follow the installation process.
If you use a 32 bits computer download Eclipse 2018-09 for Windows 32 or for Linux 32 instead of following the above steps.

Install 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:
getting-started_en010.png
As you see, OpenXava distribution includes an Eclipse workspace configured and ready to use. Let's start to work.

Creating the project in Eclipse

Start your Eclipse and open the OpenXava workspace with it (File > Switch Workspace):
quick-start_en010.png
First, you have to create a new Java project:
getting-started_en020.png
Then a wizard will appear. Just type the project name, Invoicing, and click the Finish button:
getting-started_en030.png
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:
Asking for module name
Just click on Don't Create.
After this step you have an empty Java project named Invoicing:
getting-started_en040.png
Now you must convert it into an OpenXava project:
getting-started_en050.png
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:
getting-started_en060.png
Your project is ready to start to write code.

Creating your first entity

Developing the application is very easy. You only have to add entities in order to make your application grow. We start with a simple version of Customer with only number and description.
Select the com.yourcompany.invoicing.model package and click on New Java Class button:
getting-started_en125.png
Then type Customer as class name and press Finish.
getting-started_en130.png
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 com.yourcompany.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 com.yourcompany.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:
getting-started_en145.png
Click the right mouse button on _Run_Invoicing.java (in src/_run) and select Run As > Java Application:
getting-started_en150.png
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
getting-started_en160.png
Now, enter admin/admin and click on SIGN IN:
Sign In page
Then on top the left you will have a list of modules, choose Customers:
getting-started_en170.png
Use the Customers module to create new customers, just enter number and name and press Save.
getting-started_en190.png
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 com.yourcompany.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, stop the application, build (Ctrl-B) and start the application again:
getting-started_en195.png
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:
getting-started_en200.png
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 class, 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:

Download source code of this lesson

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