Java Back-End Web App Tutorial Part 1: Building a Minimal App in Seven Steps

JavaBean Classes and Entity Classes

A JavaBean class (or, simply, bean class) is a Java class with a default constructor where all properties are serializable and have a get and set method (also called "getter" and "setter"). A Java bean is an object created with the help of a bean class.

A JPA entity class (or, simply, entity class) is a JavaBean class with an @Entity annotation, implying that a JavaEE runtime environment (such as provided by the TomEE PLUS web server) will take care of the persistent storage of its instances.

In the first step, we set up our folder structure for the application program code. The application name in this chapter will be "Public Library", and we will use a corresponding name for the application folder, "publicLibrary". Then we create the application structure. There are many ways to do this, like for example to use the Eclipse development environment (and create and configure a Dynamic Web Project). In this tutorial we show how to do it manually, so there is no need to use special tools, except ANT for being able to compile and deploy the application more easily. For your convenience, we provide an ANT script (available for download at the end of this tutorial), which is able to create the folder structure of a web application, compile it to a Web application Archive (WAR) file and then deploy it to a TomEE web server for execution. The application structure (which is compatible with the Dynamic Web Project structure of Eclipse, so it can be imported in Eclipse) is the following:

publicLibrary
  src
    pl
      model
      ctrl
    META-INF
      persistence.xml
  WebContent
    views
      books
    WEB-INF
      templates
      faces-config.xml
      web.xml

This folder structure has the following parts:

In the second step, we create the model classes for our app, using a separate Java source code file (with extension .java) for each model class. In the information design model shown in Figure 1.1 above, there is only one class, representing the object type Book. So, we create a file Book.java in the folder src/pl/model with the following code:

@Entity @Table( name="books")
public class Book {
  @Id private String isbn;
  private String title;
  private int year;
  // default constructor, required for entity classes
  public Book() {}
  // constructor
  public Book( String isbn, String title, int year) {
    this.setIsbn( isbn);
    this.setTitle( title);
    this.setYear( year);
  }
  // getter and setter methods
  public String getIsbn() {return isbn;}
  public void setIsbn( String isbn) {this.isbn = isbn;}
  public String getTitle() {return title;}
  public void setTitle( String title) {this.title = title;}
  public int getYear() {return year;}
  public void setYear( int year) {this.year = year;}
  // CRUD data management methods
  public static void add(...) {...}
  public static List<Book> retrieveAll(...) {...}
  public static Book retrieve(...) {...}
  public static void update(...) {...}
  public static void destroy(...) {...}
  public static void clearData(...) {...}
  public static void createTestData(...) {...}
}

Notice that the model class Book is encoded as a JPA entity class, which is a JavaBean class enriched with the following JPA annotations:

In the entity class Book, we also define the following static (class-level) methods:

These methods are discussed in the following sections.

The JPA architecture for data management and object-to-storage mapping is based on the concept of an entity manager, which provides the data management methods persist for saving a newly created entity, find for retrieving an entity, and remove for deleting an entity.

Since the database access operations of an entity manager are executed in the context of a transaction, our data management methods have a parameter ut of type UserTransaction. Before the entity manager can invoke the database write method persist, a transaction needs to be started with ut.begin(). After all write (and state change) operations have been performed, the transaction is completed (and all changes are committed) with ut.commit().

CREATE TABLE IF NOT EXISTS books (
  isbn VARCHAR(10) NOT NULL PRIMARY KEY,
  title VARCHAR(128),
  year SMALLINT
);

public static void add( EntityManager em, UserTransaction ut, 
    String isbn, String title, int year) throws Exception {
  ut.begin();
  Book book = new Book( isbn, title, year);
  em.persist( book);
  ut.commit();
}

public static List<Book> retrieveAll( EntityManager em) {
  Query query = em.createQuery( "SELECT b FROM Book b", Book.class);
  List<Book> books = query.getResultList();
  return books;
}

public static void update( EntityManager em, 
    UserTransaction ut, String isbn, String title, 
    int year) throws Exception {
  ut.begin();
  Book book = em.find( Book.class, isbn);
  if (!title.equals( book.getTitle())) book.setTitle( title);
  if (year != book.getYear()) book.setYear( year);
  ut.commit();
}

public static void destroy( EntityManager em, 
    UserTransaction ut, String isbn) throws Exception {
  ut.begin();
  Book book = em.find( Book.class, isbn);
  em.remove( book);
  ut.commit();
}

public static void createTestData( EntityManager em, 
    UserTransaction ut) throws Exception {
  Book book = null;
  Book.clearData( em, ut);  // first clear the books table
  ut.begin();
  book = new Book("006251587X","Weaving the Web", 2000);
  em.persist( book);
  book = new Book("0465026567","Gödel, Escher, Bach", 1999);
  em.persist( book);
  book = new Book("0465030793","I Am A Strange Loop", 2008);
  em.persist( book);
  ut.commit();
}

public static void clearData( EntityManager em, 
    UserTransaction ut) throws Exception {
  ut.begin();
  Query deleteStatement = em.createQuery( "DELETE FROM Book");
  deleteStatement.executeUpdate();
  ut.commit();
}

In this section we show how to

EntityManagerFactory emf = 
    Persistence.createEntityManagerFactory("MinimalApp");
EntityManager em = emf.createEntityManager();
EntityTransaction et = em.getTransaction();

public class BookController {
  @PersistenceContext( unitName="MinimalApp")
  private EntityManager em;
  @Resource() UserTransaction ut;

  public List<Book> getBooks() {...}
  public void refreshObject( Book book) {...}
  public String add( String isbn, String title, 
      int year) {...}
  public String update( String isbn, 
      String title, int year) {...}
  public String destroy( String isbn) {...}
}

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.1" xmlns="http://java.sun.com/xml/ns/persistence" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <persistence-unit name="MinimalApp">
    <class>pl.model.Book</class>
    <properties>	
      <!-- Request auto-generation of the database schema -->
      <property name="javax.persistence.schema-generation.database.action" 
          value="create"/>
      <!-- Use the JPA annotations for creating the database schema -->
      <property name="javax.persistence.schema-generation.create-source" 
          value="metadata"/>
    </properties>
    <jta-data-source>jdbc/MinimalApp</jta-data-source>
  </persistence-unit>
</persistence>

<?xml version="1.0" encoding="UTF-8"?>
<TomEE>
  <Resource id="MinimalApp" type="DataSource"> 
    JdbcDriver com.mysql.jdbc.Driver 
    JdbcUrl jdbc:mysql://localhost:3306/minimalapp
    UserName minimalapp 
    Password minimalapp 
    JtaManaged true 
  </Resource> 
</TomEE>

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://java.sun.com/jsf/facelets"
      xmlns:h="http://java.sun.com/jsf/html">
  <h:head>
    <title><ui:insert name="title">Public Library</ui:insert></title>
    <link href="#{facesContext.externalContext.requestContextPath}/resources/css/style.css" 
          rel="stylesheet" type="text/css" />
  </h:head>
  <body>
    <div id="header">
      <ui:insert name="header">
        <ui:include src="/WEB-INF/templates/header.xhtml"/>
      </ui:insert>
    </div>
    <div id="main">
      <ui:insert name="main"/>
    </div>
    <div id="footer">
      <ui:insert name="footer">
        <ui:include src="/WEB-INF/templates/footer.xhtml"/>
      </ui:insert>
    </div>
  </body>
</html>

<div><h2>Public Library</h2></div>

<div>Copyright 2014-2015, Gerd Wagner and Mircea Diaconescu</div>

@Entity @Table( name="books")
@RequestScoped @ManagedBean( name="book")
public class Book { ... }

@SessionScoped @ManagedBean( name="bookCtrl")
public class BookController { ... }

The Create use case involves creating a new object in main memory and then saving it to persistent storage with the help of the add method.

The corresponding add action method code from the src/pl/ctrl/BookController.java is shown below:

public class BookController {
  ...
  public String add( String isbn, String title, int year) {
    try {
      Book.add( em, ut, isbn, title, year);
      // clear the form after saving the Book record
      FacesContext fContext = FacesContext.getCurrentInstance();
      fContext.getExternalContext().getRequestMap().remove("book");
    } catch ( Exception e) {
      e.printStackTrace();
    } 
    return "create";
  }
}

The BookController::add action method invokes the Book.add model class method for creating and saving a Book instance. It returns the name of the view file found in the same folder as the view that triggered the action. This file (create.xhtml in our case) will be displayed after executing the action. In lines 5 and 6 above, using a FacesContext object, the form is cleared after creating a Book instance. The code of the add method in src/pl/model/Book.java is the following:

public class Book {
  ...
  public static void add( EntityManager em, UserTransaction ut,
      String isbn, String title, int year) throws Exception {
    ut.begin();
    Book book = new Book( isbn, title, year);
    em.persist( book);
    ut.commit();
  }
}

Now we need to create the facelet view file for the Create use case, WebContent/views/books/create.xhtml. Such a facelet file essentially defines a HTML form with data binding and action binding.

Data binding refers to the binding of model class properties to form (input or output) fields. For instance, in the following facelet code fragment, the entity property book.isbn is bound to the form input field "isbn":

<h:outputLabel for="isbn" value="ISBN: " />
<h:inputText id="isbn" value="#{book.isbn}" />

Action binding refers to the binding of method invocation expressions to actionable UI elements, where the invoked methods typically are controller action methods, and the actionable UI element typically are form buttons. For instance, in the following facelet code fragment, the method invocation expression bookCtrl.add(...) is bound to the form's submit button:

<h:commandButton value="Create" 
    action="#{bookCtrl.add( book.isbn, book.title, book.year)}"/>

After discussing data binding and action binding, it's time to look at the complete code of the facelet:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="..."
      xmlns:h="..." xmlns:p="...">
  <ui:composition template="/WEB-INF/templates/page.xhtml">
    <ui:define name="main">
      <h:form id="createBookForm">
        <h:panelGrid columns="2">
          <h:outputLabel for="isbn" value="ISBN: " />
          <h:inputText id="isbn" value="#{book.isbn}" />
          <h:outputLabel for="title" value="Title: " />
          <h:inputText id="title" value="#{book.title}" />
          <h:outputLabel for="year" value="Year: " />
          <h:inputText id="year" p:type="number" value="#{book.year}" />
        </h:panelGrid>
        <h:commandButton value="Create" 
            action="#{bookCtrl.add( book.isbn, book.title, book.year)}"/>
      </h:form>
      <h:button value="Main menu" outcome="index" />
    </ui:define>
  </ui:composition>
</html>

This facelet replaces the main region of the template defined in page.xhtml, because the name attribute of the ui:define element has been set to "main".

h:outputLabel elements can be used for creating form field labels, while h:inputText elements are used for creating HTML input elements. It is possible to specify a HTML5 type of an input element by using a special namespace prefix (xmlns:p="http://xmlns.jcp.org/jsf/passthrough") for the type attribute, enforcing it to be 'passed through'. In this way the year input field can be defined with type number, so it's rendered by the corresponding number widget in the browser.

The h:commandButton element allows creating submit buttons rendered as a input elements with type="submit", and binding them to an action to be performed when the button is clicked. The value of the action attribute is a method invocation expression. In our Create use case we want that, when the button is clicked, a Book instance with the property values provided by corresponding form fields is created and saved.

This use case corresponds to the "Retrieve/Read" from the four basic data management use cases Create-Retrieve-Update-Delete (CRUD).

First of all, for the list objects use case we have to add a method in the controller class (src/pl/ctrl/BookController.java file), which reads all the Book records from the books database table and then delivers this information to the view. The controller action method code is shown below:

public class BookController {
  ...
  public List<Book> getBooks() {
    return Book.retrieveAll( em);
  }
  ...
}

The getBooks method returns a list of Book instances which are obtained by calling the static retrieveAll method of the Book model class. The code of the Book.retrieveAll method is:

public class Book {
  ...
  public static List<Book> retrieveAll( EntityManager em) {
    Query query = em.createQuery( "SELECT b FROM Book b");
    List<Book> books = query.getResultList();
    return books;
  }
  ...
}

The code is simple, and as already discussed in Section 2.3, it uses a JPQL statement to retrieve the Book records from the books table and create the corresponding Book instances. The EntityManager object required for being able to perform the JPQL query is passed to Book.retrieveAll from the BookController object as discussed in Section 3.1 section.

Now, it is the time to define the facelet view which is used to display a table with all the records found in the database. The view files corresponding to our application are located under WebContent/views/books folder. For the Retrieve/list all use case, we create a file named listAll.xhtml with the following content:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="..."
      xmlns:h="..." xmlns:f="...">
  <ui:composition template="/WEB-INF/templates/page.xhtml">
    <ui:define name="main">
      <h:dataTable value="#{bookCtrl.books}" var="b">
        <h:column>
          <f:facet name="header">ISBN: </f:facet>
          #{b.isbn}
        </h:column>
        <h:column>
          <f:facet name="header">Title: </f:facet>
          #{b.title}
        </h:column>
        <h:column>
          <f:facet name="header">Year: </f:facet>
          #{b.year}
        </h:column>
      </h:dataTable>
      <h:button value="Main menu" outcome="index" />
    </ui:define>
  </ui:composition>
</html>

The ui:composition element specifies which template is applied (i.e. template="/WEB-INF/templates/page.xhtml") and which view block (<ui:define name="main">) is replaced by this facelet at render time.

The h:dataTable element defines a table view for a set of records, which is then rendered as an HTML table. Its value attribute defines a data binding to a record collection, while the var attribute defines a variable name for iteratively accessing records from this collection. The expression provided in the value attribute normally specifies a collection-valued property (here: books) which is accessed via a corresponding getter (here: getBooks) as defined in the controller class BookController. In this particular case it is just sufficient to define the getBooks method since there is no need of a books property in the controller class. In any case, value does not allow to invoke a method, so we cannot call getBooks directly. Instead we have to use the (possibly virtual) property books, which internally evaluates to a call of getBooks without checking if a books property really exists.

The h:button JSF element allows to create redirect buttons. The value of the outcome attribute specifies a name of a JSF view file by omitting the .xhtml extension (i.e. the view file name is index.xhtml).

This use case corresponds to the "Update" from the four basic data management use cases Create-Read-Update-Delete (CRUD).

As for the create object use case, a controller action method is defined in the BookController class (src/pl/ctrl/BookController.java file) with the following code:

public String update( String isbn, String title, int year) {
  try {
    Book.update( em, ut, isbn, title, year);
  } catch ( Exception e) {
    e.printStackTrace();
  } 
  return "update";
}

The Book.update takes care of updating and making persistent changes for the book entry identified by the provided isbn value as shown below:

public static void update( EntityManager em, UserTransaction ut,
    String isbn, String title, int year) throws Exception {
  ut.begin();
  Book book = em.find( Book.class, isbn);
  book.setTitle( title);
  book.setYear( year);
  ut.commit();
}

Now, we create the view where a Book can be selected so the user can edit the title and year properties, and then save the changes. The code for this view is stored in the WebContent/views/books/update.xhtml file which has the following content:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="..."
      xmlns:h="..." xmlns:f="..." xmlns:p="...">
  <ui:composition template="/WEB-INF/templates/page.xhtml">
    <ui:define name="main">
      <h:form id="updateBookForm">
        <h:panelGrid columns="2">
          <h:outputLabel for="selectBook" value="Select book: " />
          <h:selectOneMenu id="selectBook" value="#{book.isbn}">
            <f:selectItem itemValue="" itemLabel="---" />
            <f:selectItems value="#{bookCtrl.books}" var="b" 
                itemValue="#{b.isbn}" itemLabel="#{b.title}" />
            <f:ajax listener="#{bookCtrl.refreshObject( book)}" 
             render="isbn title year"/>
          </h:selectOneMenu>
          <h:outputLabel for="isbn" value="ISBN: " />
          <h:outputText id="isbn" value="#{book.isbn}" />
          <h:outputLabel for="title" value="Title: " />
          <h:inputText id="title" value="#{book.title}" />
          <h:outputLabel for="year" value="Year: " />
          <h:inputText id="year" p:type="number" value="#{book.year}" />
        </h:panelGrid>
        <h:commandButton value="Update" 
            action="#{bookCtrl.update( book.isbn, book.title, book.year)}"/>
      </h:form>
      <h:button value="Main menu" outcome="index" />
    </ui:define>
  </ui:composition>
</html>

In this view, a single selection list (select) element is created by using h:selectOneMenu. The @value attribute allows to save the value of selection by assigning it to a property of an object. In our case, since the selected Book is identified by its isbn property value which is stored in the book.isbn property. Populating the list with book records is performed by using the f:selectItems element, which requires a list of records (using the @value attribute), as well as defining a variable name (using @var attribute) which is bound to the element of the list which is has the cursor in the loop used internally to populate the select list. The attributes @itemValue and @itemLabel are used to provide the information used to create the option HTML5 elements when the view is rendered, by specifying the content of the option element (i.e. the value of the @itemLabel attribute) and the value of the option/@value attribute (i.e. the value of @itemValue attribute).

In the update view, the user selects a book from the drop-down list, while the rest of the form has to be auto-completed with the details (isbn, title and year) of the selected book. The ISBN we already know, being the selection value of the drop-down list. However, we need to show also the title and year of the selected book. To do this, we use f:ajax JSFelement which allows to perform a request (an AJAX request) which results in calling a specified method. The method will get as parameter the managed book instance, and updates its title and year properties with the right values by reading them from the database. The used method is part of the BookController class and is named refreshObject. The code of this method is shown below:

public void refreshObject( Book book) {
  Book foundBook = Book.retrieve( em, book.getIsbn());
  book.setTitle( foundBook.getTitle());
  book.setYear( foundBook.getYear());
}

It simply uses the Book.retrieve method which returns the Book instance stored in the database for the given isbn value. Then, the reference parameter of the method (i.e. book) is then updated so the title and year have the correct values. In the view code, we parse the reference of the book as value of the refreshObject method. The book properties are connected with the h:inputText and h:outputText (for isbn which must be read only) JSF elements, which means the form input elements will be display the values of the book properties. To enforce the refresh of the form (this is required, because the form updates automatically only on submit actions), so it displays the updated isbn, title and year values, the f:ajax JSF element allows to specify the form (to which the f:ajax is child of) elements to be updated, i.e. f:ajax/@render="isbn title year" in our case.

Last, the h:commandButton specifies that the action is to invole the update action method of the BookController with the parameters isbn, title and year, so the the changes are made persistent.

This use case corresponds to the "Delete" from the four basic data management use cases Create-Read-Update-Delete (CRUD).

The corresponding destroy action method code from the src/pl/ctrl/BookController.java is presented below:

public String destroy( String isbn) {
  try {
    Book.destroy( em, ut, isbn);
  } catch ( Exception e) {
    e.printStackTrace();
  } 
  return "delete";
}

The main functionality of the controller action method is to invoke the Book.destroy method and provide the isbn of the Book entry to be deleted. The Book.destroy method takes care of finding the right entry (based on the given value of the standard identifier, i.e. isbn) as well as deleting it from the database.

public static void destroy( EntityManager em, UserTransaction ut, String isbn) 
       throws Exception, HeuristicRollbackException, RollbackException {
  ut.begin();
  Book book = em.find( Book.class, isbn);
  em.remove( book);
  ut.commit();
}

Finding the Book entry with the given isbn value is easy by using the builtin find method of the EntityManager object (see Section 2.4). Removing the Book entry from the database is performed by simply invoking the remove method of the EntityManager object (more details: Section 2.5 ).

The last thing we have to do is to create the associated view for the delete action. The view contains a drop-down list which allows to select the Book to be deleted, then a "Delete" button performs the deletion of the book. The code of the view (WebContent/views/books/delete.xhtml) file si shown below

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="..."
      xmlns:h="..."
      xmlns:f="...">

  <ui:composition template="/WEB-INF/templates/page.xhtml">
    <ui:define name="main">
      <h:form id="deleteBookForm">
        <h:panelGrid columns="2">
          <h:outputText value="Select book: " />
          <h:selectOneMenu value="#{book.isbn}">
            <f:selectItems value="#{bookCtrl.books}" var="b" 
                itemValue="#{b.isbn}" itemLabel="#{b.title}" />
          </h:selectOneMenu>
        </h:panelGrid>
        <h:commandButton value="Delete" 
            action="#{bookCtrl.destroy( book.isbn)}"/>
      </h:form>
      <h:button value="Main menu" outcome="index" />
    </ui:define>
  </ui:composition>
</html>

As in the update object use case, a h:selectOneMenu JSF element is used to create and populate a drop-down list containing all the books, so we can choose which one we like to delete. Clicking on "Delete" h:commandButton results in performing the associated action which invokes the destroy action method of the controller with the isbn value of the selected book, thus resulting in the deletion of the Book entry from the database.

You can run the minimal app on our server or download the code as a ZIP archive file.

For running the minimal app on your computer, first download the code and edit the ANT script file by modifying the server.folder property value as described in Section 3.5. You may then have to stop your Tomcat/TomEE server with bin/shutdown.bat for Windows or bin/shutdown.sh for Linux. Now execute the following command in your console or terminal: ant deploy -Dappname=minimalapp. Last, start your Tomcat web server (by using bin/startup.bat for Windows OS or bin/startup.sh for Linux). Please be patient, this can take some time depending on the speed of your computer. It will be ready when the console displays the following info: INFO: Initializing Mojarra [some library versions and paths are shonw here] for context '/minimalapp'. Finally, open your favorite browser and type: http://localhost:8080/minimalapp/faces/views/books/index.xhtml

For new projects, you may want to download the dependency libaries.

The code of this app should be extended by

We show how to do this in the follow-up tutorial Building Java Web Apps Tutorial Part 2: Adding Constraint Validation.

We briefly discuss three further points of attention: boilerplate code, code clarity, using resource URLs and architectural separation of concerns.