Getting started with OpenXava using Maven

Creating a new project

First, you have to create a new OpenXava project from command line using Maven, type the next commands for Windows, Linux or Mac:

$ mvn archetype:generate -DarchetypeGroupId=org.openxava -DarchetypeArtifactId=openxava-archetype -DarchetypeVersion=RELEASE -DgroupId=com.yourcompany -DartifactId=invoicing -DinteractiveMode=false
$ cd invoicing
$ mvn package

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 name.

You have to create a Customer.java file in the folder src/main/java/com/yourcompany/invoicing/model of this project, then write the code below:

package com.yourcompany.invoicing.model;
 
import javax.persistence.*;
import org.openxava.annotations.*;
import lombok.*;
 
@Entity  // This marks Customer class as an entity
@Getter @Setter // This makes all fields below publicly accessible
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
    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
    String name;
 
}

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

Running the application

Type the next commands, in Windows:

c:\> mvn compile
c:\> java -cp "target/invoicing/WEB-INF/classes;target/invoicing/WEB-INF/lib/*" com.yourcompany.invoicing.run.invoicing

In Linux o Mac:

$ mvn compile
$ java -cp "target/invoicing/WEB-INF/classes:target/invoicing/WEB-INF/lib/*" com.yourcompany.invoicing.run.invoicing

Wait until the console shows a message saying "Application started", like this:

Then your application is already running. To check this, open your favorite browser (Chrome, Firefox, 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

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 first OpenXava 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.

Create a Product.java file in the folder src/main/java/com/yourcompany/invoicing/model of this project, then write the code below:

package com.yourcompany.invoicing.model;
 
import javax.persistence.*;
import org.openxava.annotations.*;
import lombok.*;
 
@Entity @Getter @Setter
public class Product {
 
    @Id @Column(length=9)
    int number;
 
    @Column(length=50) @Required
    String description;
 
}

Now, restart your application, don't forget to compile again, in Windows:

c:\> mvn compile
c:\> java -cp "target/invoicing/WEB-INF/classes;target/invoicing/WEB-INF/lib/*" com.yourcompany.invoicing.run.invoicing

In Linux o Mac:

$ mvn compile
$ java -cp "target/invoicing/WEB-INF/classes:target/invoicing/WEB-INF/lib/*" com.yourcompany.invoicing.run.invoicing

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.

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 guide, getting started using Maven, is the lesson 1 of a complete OpenXava course. The rest of the course is in Eclipse and will 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:

Getting started:

Lesson 1: Getting started (You're here)

Modeling with Java:

Lesson 2: Basic domain model - Part 1 (Your next step)
Lesson 3: Basic domain model - Part 2
Lesson 4: Refining the user interface
Lesson 5: Agile development

Inheritance:

Basic business logic:

Advanced validation:

Refining the standard behavior:

Lesson 24: Refining the standard behavior

Behavior & business logic:

Lesson 25: Behavior & business logic

References & collections:

Lesson 26: References & collections

Appendices:

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.

Do you want to use IntelliJ or Visual Studio Code? 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