Introduction

The purpose of this tutorial is to demonstrate the basic usage of Enterprise App for Vaadin. We will develop a simple Address Book using Eclipse, Vaadin Eclipse plugin, and Enterprise App.

Download source code (no jars included, please download from Vaadin Directory)

Download Enterprise App for Vaadin

Enterprise App for Vaadin is available for download at Vaadin Directory. You can download a free version for use in open-source projects (if you are planning to close your code, you must purchase a license).

Eclipse Vaadin Project

Start Eclipse and create a new Vaadin project:

Click Next three times and configure the Vaadin specific project details:

Click finish and let Eclipse create the new project.

Libraries and Dependencies

In order to use Enterprise App you must include the add-on jar and its dependencies to your classpath. This can easily be done by dropping enterprise-app.jar along with all the jars inside the dependencies directory of the add-on package to the WEB-INF/lib directory of your project. You will need to add the jar for your JDBC Driver. In this tutorial we will use an in-memmory HSQLDB database to persist our data, so we also need to add hsqldb.jar to the classpath.

The Persistence Unit

As we are using Hibernate as our ORM technology, we need to add a persistence unit to our project.  Right click your Eclipse project and select Properties from the context menu. Click on Project Facets and select JPA:

Click on Further configuration available below the Project Facets box and select Generic as platform. Click OK two times to add the new facet. Eclipse must have added a new persistence.xml file to your project. Check that the file declares a persistence unit named enterprise-app-tutorial.

Data Transfer Objects

Enterprise App uses the Data Transfer Objects (DTOs) pattern to store application data. You can think of DTOs as JPA/Hibernate Entities. For this tutorial, we need one Entity class: Person. Right click the enterpriseapp.tutorial package and select New->other. Select JPA Entity from the list and click Next. Complete the required fields as shown below:

Click Finish to create the new Entity and edit the file (Person.java) content to match the following:

package enterpriseapp.tutorial;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

import enterpriseapp.hibernate.dto.Dto;

@Entity
public class Person extends Dto {
	
	private static final long serialVersionUID = 1L;
	
	@Id
	@GeneratedValue(strategy=GenerationType.AUTO)
	private Long id;
	
	@Column(nullable=false)
	private String name;
	
	private String phoneNumber;

	@Override
	public Long getId() {
		return id;
	}

	@Override
	public void setId(Object id) {
		this.id = (Long) id;
	}
   
	public void setId(Long id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getPhoneNumber() {
		return phoneNumber;
	}

	public void setPhoneNumber(String phoneNumber) {
		this.phoneNumber = phoneNumber;
	}
}

As you can see, the Entity class must extend Dto. Dto implements hashCode(), equals() and toString() methods in order to avoid boilerplate code in your domain clases. Of course, you can override this methods when you need to (if you are as lazy as I am, take a look at Project Lombok).

Dto forces you to implement getId() and setId(Object id). You've got to provide a setter with an argument matching the id property type (in this case, we implemented setId(Long id) which takes a Long argument).

A Powerful CRUD Interface

Now we are ready to implement that really cool CRUD interface for our Entities. Enterprise App makes it dead easy to do this. Edit your TutorialEnterpriseApplication.java to match the following content:

package enterpriseapp.tutorial;

import com.vaadin.ui.Window;

import enterpriseapp.EnterpriseApplication;
import enterpriseapp.ui.crud.CrudBuilder;
import enterpriseapp.ui.crud.CrudComponent;

public class TutorialEnterpriseApplication extends EnterpriseApplication {
	
	private static final long serialVersionUID = 1L;

	@Override
	public void init() {
		super.init();
		
		CrudComponent crud = new CrudBuilder(Person.class).build();
		crud.setSizeFull();
		
		Window mainWindow = new Window("Address Book");
		mainWindow.setSizeFull();
		mainWindow.setContent(crud);
		setMainWindow(mainWindow);
	}

}

Pretty short class, isn't it? Before we can deploy and run our application, we must configure a ServletContextListener and create a configuration.properties file.

The Default Context Listener

By configuring a DefaultContextListener in your web.xml file, Enterprise App will be able to automatically start everything up. This includes loading properties files and initializing Hibernate and Quartz according to the application's configuration.

Add the DefaultContextListener reference into your web.xml:

<listener>
	<listener-class>enterpriseapp.DefaultContextListener</listener-class>
</listener>

Configuration Properties

Enterprise App for Vaadin allows you to configure your application from configuration files. Create a new configuration.properties file in your src directory. Your Eclipse package explorer must now look like this:

Edit your configuration.properties file to match the following content (take a look at the defaultConfiguration.properties file inside enterprise-app.jar):

db.persistenceUnit=enterprise-app-tutorial
db.driver=org.hsqldb.jdbcDriver
db.dialect=org.hibernate.dialect.HSQLDialect
db.url=jdbc:hsqldb:mem:snb-test
db.user=sa
db.password=
db.schemaGeneration=update
db.show_sql=true
db.interceptor=enterpriseapp.hibernate.LogBasedAuditInterceptor

Deploy and Run your Enterprise Application

We are ready now! Deploy your web application to any Java servlet container (such as Apache Tomcat or Glassfish) and browse to http://localhost:8080/enterprise-application-tutorial (or whatever URL your application has been deployed to). You will see a CRUD interface with filtering, import/export capabilities and some other cool features.

Enjoy!