openxava / documentation / Getting started with OpenXava

Follow this guide to create and run your first OpenXava project. También disponible en Español.

Creating a new project

First, you have to create a new Java project:
getting-started_en020.png
Then a wizard will appear. Just type the project name, Invoicing. Beware of writing the I of Invoicing in uppercase in order that the links below work correctly. Click the Finish button:
getting-started_en030.png
Then OpenXava Studio 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.
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 Invoicing/src/_run) and select Run As > Java Application:
getting-started_en150.png
Your application is already running. To check this, open your favorite browser (Chrome, Firefox, Internet Explorer 11, Edge or Safari) and go to the next 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 create a new entity for Product.
Select the com.yourcompany.invoicing.model package and click on New Java Class button:
getting-started_en125.png
Then type Product as class name and press Finish.
getting-started_en193.png
Write the next code for Product:
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.

Any problem?

Congratulations! You have created your first OpenXava application. Otherwise, if you have had any problem with the above example, ask in the forum:

    Ask in the forum

We'll help you to overcome any difficulty.

Next steps

This getting started guide is the lesson 1 of a complete OpenXava course. This course is meant to teach you how to develop enterprise applications with OpenXava as well as other Java related technologies, tools and frameworks. Together we will develop step by step a complete application from scratch. 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.
This is the content 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:


Do you want to use IntelliJ? Do you want to go against MySQL, PostgreSQL, Oracle, Microsoft SQL Server, AS/400, Informix, Db2 or Firebird? Do you want a detailed reference guide? Look at the OpenXava documentation, that includes this and much more.


Are you ready? Go to Lesson 2