What About Java EE?

Note that you do not need to download and install Java EE from Oracle.com even though JSF itself is part of Java EE . Java EE is basically an abstract specification of which the so-called application servers represent the concrete implementations. Examples of those application servers are Payara, WildFly, TomEE, GlassFish, and Liberty. It is exactly those application servers that actually provide among others JSF (JavaServer Faces), EL (Expression Language), CDI (Contexts and Dependency Injection), EJB (Enterprise JavaBeans), JPA (Java Persistence API), Servlet, WebSocket, and JSON-P (JavaScript Object Notation Processing), APIs (application programming interfaces) out of the box.

There also exist so-called servlet containers which provide basically only the Servlet, JASPIC (Java Authentication Service Provider Interface for Containers), JSP (JavaServer Pages), EL, and WebSocket APIs out of the box, such as Tomcat and Jetty. However, it would require some work to manually install and configure, among others, JSF, JSTL (JSP Standard Tag Library), CDI, EJB, and JPA on such a servlet container. It is not even trivial in the case of EJB as it requires modifying the servlet container’s internals. That is, by the way, exactly why TomEE exists. It’s a Java EE application server built on top of the barebones Tomcat servlet container engine.

Coming back to the Java EE download at Oracle.com, it would give you basically the GlassFish server, along with a bunch of documentation and optionally the Netbeans IDE. We do not need it as we are already using Payara as the Java EE application server, and are targeting Eclipse as IDE. Therefore, the Java SE JDK is sufficient.

How About Other Servers?

The choice for Payara in this book is primarily because it is at time of this writing one of the very few available Java EE application servers with JSF 2.3 integrated. The other one is GlassFish, but we would rather not advocate it as it would basically offer no commercial support or bug fixes. GlassFish must be seen as a true reference implementation for other application server vendors so they can, if necessary, build their application server implementation by example.

WildFly, TomEE, and Liberty did not, at the time of writing, have a version available with JSF 2.3 integrated.

Configuring Eclipse

Before we can start writing code, we would like to fine-tune Eclipse a bit so that we don’t eventually end up in trouble or with annoyances. Eclipse has an enormous amount of settings, and some of its default values should not have been the default values. You can verify and configure the settings via Window ➤ Preferences.

• General ➤ Workspace ➤ Text file encoding must be set to UTF-8. Particularly in Windows this might otherwise default to the proprietary encoding CP-1252 which does not support any characters beyond the Latin range. When reading and saving Unicode files with CP-1252, you risk seeing unintelligible sequences of characters. This is also called “mojibake.”.¹

• General ➤ Workspace ➤ New text file line delimiter must be set to Unix. It works just fine on Windows as well. This will particularly keep version control systems happy. Otherwise, developers pulling code on different operating systems might face confusing conflicts or diffs caused by different line endings.

• General ➤ Editors ➤ Text editors ➤ Spelling should preferably be disabled. This will save you from a potentially big annoyance, because it unnecessarily also spellchecks XML configuration files such as faces-config.xml and web.xml, causing confusing errors and warnings in those files.

• Java ➤ Compiler ➤ Compiler compliance level must be set to 1.8. This is the minimum required Java version for Java EE 8.

• Java ➤ Installed JREs must be set to the JDK, not to the JRE. This setting will normally also be used to execute the integrated application server which usually requires the JDK.

Installing JBoss Tools Plug-in

Standard Eclipse for Java EE in its current version does not support any CDI tools. It has no wizards to create CDI managed beans, or autocompletion and hyperlinking for CDI managed beans in JSF pages. The JBoss Tools plug-in is an extensive plug-in which offers among others the CDI tools.² This is very useful when developing a Java EE web application.

In order to install it, go to Help ➤ Eclipse Marketplace. Enter in the search field “JBoss Tools” and click Go. Scroll a bit through the results until you see JBoss Tools Final and then click Install (see Figure 2-2).

Figure 2-2 JBoss Tools in the Eclipse Marketplace

In the next step, you’ll see a fairly large list of all JBoss Tools’ offerings. We don’t need all of them. The list indeed also includes some JSF-related tools, but they are not terribly useful. The Visual Page Editor is not at all useful. Dragging and dropping together a JSF page doesn’t make you a good JSF developer. That can only be achieved by just writing code yourself. Moreover, having too many unused features installed and even implicitly enabled may make Eclipse terribly slow. The fewer features you select, the less chance that you will be surprised about changes in the IDE behavior. So, untick the top check box and then tick only the check box which says “Context and Dependency Injection Tools” (see Figure 2-3).

Figure 2-3 Select only the CDI tools for now

Next, accept the terms of the license agreement and complete the wizard until Eclipse is restarted.

Integrating New Server in Eclipse

We need to familarize Eclipse with any installed application servers so that Eclipse can seamlessly link its Java EE API libraries in the project’s build path (read: the compile time classpath of the project). This is mandatory in order to be able to import classes from the Java EE API in your project. You know, the application server itself represents the concrete implementation of the abstract Java EE API.

In order to integrate a new application server in Eclipse, first check the bottom section of the workbench with several tabs representing several Views (you can add new ones via Window ➤ Show View). Click the Servers tab to open the servers view (see Figure 2-4). Click the link which says “No servers are available. Click this link to create a new server. . . .”

Figure 2-4 Servers view of Eclipse Workbench

From the list of available server tools, select Oracle ➤ GlassFish Tools (see Figure 2-5).

Figure 2-5 Selecting GlassFish Tools in New Server wizard

After clicking Next for the first time , it will download the plug-in in the background and request you to accept the license agreement before installing the plug-in. This plug-in is mandatory in order to manage any GlassFish-based server from inside the workbench—among others, adding and removing Eclipse projects to the deployments folder, starting and stopping the server, and running the server in debug mode. Once it’s finished installing, it will request you to restart Eclipse. Take action accordingly.

Once returned into the workspace, click the same link in the Servers view again. You’ll now see a GlassFish ➤ GlassFish option . Select this and set the Server name field to “Payara” (see Figure 2-6).

Figure 2-6 Selecting GlassFish server in New Server wizard and naming it Payara

Advance to the next step. Here, you should point the GlassFish location field to the glassfish subfolder of the Payara installation, there where you have unzipped it after downloading (see Figure 2-7).

Figure 2-7 Specifying GlassFish location in New Server wizard

Complete the remainder of the New Server wizard with default settings. You don’t need to edit any other fields. The newly added server will now appear in the Servers view (see Figure 2-8).

Figure 2-8 The Payara server in Servers view

Creating the Backing Bean Class

With the project now correctly configured we can start with developing the actual MVC application . The Controller part of MVC is already configured as FacesServlet in web.xml. The Model part of MVC is what we’re going to create now. It’s basically just a simple Java class which is by JSF convention called a Backing Bean since it “backs” a View.

Right-click the src/main/java folder of the project and choose New ➤ Bean. The New CDI Bean wizard which appears now is also part of the JBoss Tools plug-in (see Figure 2-17). In this wizard, set the Package to com.example.project.view, set the Name to HelloWorld, tick the Add @Named chec kbox, and finally set the Scope to @RequestScoped. The rest of the fields can be kept default or empty.

Figure 2-17 The JBoss Tools-provided New CDI Bean wizard in Eclipse

The class editor will now open with the newly created backing bean class . We’ll modify it to get rid of the useless constructor; add two properties, input and output; and accompany the input property with a getter and setter pair, the output property with only a getter, and a submit() action method which prepares the output property based on the input property. As a hint, in Eclipse after entering the properties, you can right-click anywhere in the class editor and choose Source ➤ Generate Getters and Setters to have the IDE to generate them. In its entirety, the edited backing bean class should look as follows:

package com.example.project.view;

import javax.enterprise.context.RequestScoped;
import javax.inject.Named;

@Named @RequestScoped
public class HelloWorld {

    private String input;
    private String output;

    public void submit() {
        output = "Hello World! You have typed: " + input;
    }

    public String getInput() {
        return input;
    }

    public void setInput(String input) {
        this.input = input;
    }

    public String getOutput() {
        return output;
    }
}

We'll briefly go through the annotations that are used here.

• @Named—gives the bean a name, which is primarily used to reference it via EL. Without any attributes this name defaults to the simple class name with the first letter in lowercase, thus "helloWorld" here. It will be available by #{helloWorld} in EL . This can be used in JSF pages.

• @RequestScoped—gives the bean a scope, which means the same instance of the bean is used within a given lifespan. In this case that lifespan is the duration of an HTTP request. When the scope ends, the bean is automatically destroyed. You can read more about scopes in Chapter 8.

Creating the Facelets File

Next, we'll create the View part of MVC. It’s basically just a XHTML file which is by JSF interpreted as a Facelets file or just Facelet. This Facelets file will ultimately generate the HTML markup that is sent to the browser in response to a request. With help of EL, it can reference a bean property and invoke a bean action.

Right-click the webapp folder of the project and choose New ➤ XHTML Page (see Figure 2-18). The New XHTML Page wizard which appears now is also part of the JBoss Tools plug-in. In this wizard, set the File name to hello.xhtml and finish the wizard.

Figure 2-18 The JBoss Tools-provided New XHTML Page wizard in Eclipse

The XHTML editor will now open with the newly created Facelets file. You’ll also notice that the Palette view shows up in bottom box . This is essentially not useful for JSF-based web development. So let’s close it. Coming back to the newly created Facelets file, it’s initially empty. Fill it with the following content:

<!DOCTYPE html>
<html lang="en"
    xmlns:="http://www.w3.org/1999/xhtml"
    xmlns:f="http://xmlns.jcp.org/jsf/core"
    xmlns:h="http://xmlns.jcp.org/jsf/html"
>
    <h:head>
        <title>Hello World</title>
    </h:head>
    <h:body>
        <h1>Hello World</h1>
        <h:form>
            <h:outputLabel for="input" value="Input" />
            <h:inputText id="input" value="#{helloWorld.input}" />
            <h:commandButton value="Submit"
                action="#{helloWorld.submit}">
                <f:ajax execute="@form" render=":output" />
            </h:commandButton>
        </h:form>
        <h:outputText id="output" value="#{helloWorld.output}" />
    </h:body>
</html>

We'll briefly go through the JSF-specific XHTML tags that are used here.

• <h:head>—generates the HTML <head>. It gives JSF the opportunity to automatically include any necessary JavaScript files, such as the one containing the necessary logic for <f:ajax>.

• <h:body>—generates the HTML <body>. You can also use a plain HTML <body> in this specific Facelet, but then it doesn’t give any other JSF tag the opportunity to automatically include any necessary JavaScript in the end of the HTML <body>.

• <h:form>—generates the HTML <form>. JSF will automatically include the view state in a hidden input field.

• <h:outputLabel>—generates the HTML <label>. You can also use a plain HTML <label> in this specific Facelet, but then you’d have to manually take care of figuring out the actual ID of the target input element.

• <h:inputText>—generates the HTML <input type="text">. JSF will automatically get and set the value in the bean property specified in the value attribute.

• <h:commandButton>—generates the HTML <input type="submit">. JSF will automatically invoke the bean method specified in the action attribute.

• <f:ajax>—generates the necessary JavaScript code for Ajax behavior. You can also do as well without it, but then the form submit won’t be performed asynchronously. The execute attribute indicates that the entire <h:form> must be processed on submit and the render attribute indicates that the tag identified by id="output" must be updated on complete of the Ajax submit.

• <h:outputText>—generates the HTML <span>. This is the one being updated on completion of the Ajax submit. It will merely print the bean property specified in the value attribute.

Those JSF-specific XHTML tags are also called JSF Components. There will be more on Facelets files and JSF components in the upcoming chapters. Note that you can also perfectly embed plain vanilla HTML in a Facelets file. JSF components should only be used when the functionality requires so, or is easily achievable with them.

Deploying the Project

In the Servers view, first start the Payara server. You can do so by selecting it and then clicking the green arrow icon whose tool tip says “Start the server.” You can, of course, also use the bug icon whose tool tip says “Start the server in debug mode.” The Console view will briefly show the server startup log. Wait until the server starts up and has, in the Servers view, gained the status Started (see Figure 2-19).

Figure 2-19 The Payara server in Servers view with the status Started (note that the Console view is highlighted as it has unread server logs)

Now right-click the Payara server entry and choose Add and Remove. It will show the Add and Remove wizard (see Figure 2-20) which gives you the opportunity to add and remove WAR projects to the server. Do so for our newly created project and finish the wizard.

Figure 2-20 The Add and Remove wizard wherein the project has been deployed to the server by moving it to the right

It must be explicitly mentioned that in case of Payara and GlassFish servers this is best to be done while the server is already started. When removing a project while the server is shut down, it may still linger around in the server’s deployment folder. That’s just GlassFish’s own quirk. For example, in the case of WildFly and Tomcat servers, this is not necessary.

Now, open a tab in your favorite web browser (see Figure 2-21) and enter the address http://localhost:8080/project/hello.xhtml in order to open the newly created JSF page.

Figure 2-21 The Hello World page in Chrome browser wherein the input field is filled with the text “some message” and the submit button has been pressed

Coming back to the URL , the "localhost:8080" part is by convention the default domain of any Java EE server which is running in development mode. The same address is also used by, among others, WildFly and TomEE. The "/project" part is by convention the name of the Eclipse project. This is in Servlet terms called the “context path” and obtainable by HttpServletRequest#getContextPath() and in JSF delegated by ExternalContext#getRequestContextPath().

The context path part can also be set to an empty string; the deployed web application will then end up in the domain root. In Eclipse, this can be set in the project’s properties as well. First remove the project from the deployment using the Add and Remove wizard. Then right-click the project, choose Properties, and select Web Project Settings. Then set the Context root field to a forward slash “/” and close the properties. Finally, add the project back to the deployment using Add and Remove wizard. Now it will be deployed to the domain root and you can access the JSF page by http://localhost:8080/hello.xhtml. We can even get a step further by making hello.xhtml the default landing file so that this also doesn’t need to be specified in the URL. This can be achieved by adding the following entry to the web.xml:

<welcome-file-list>
    <welcome-file>hello.xhtml</welcome-file>
</welcome-file-list>

Note that Payara can be configured to automatically publish changes to the deployment whenever a resource is changed in the project. Before saving the edited web.xml, double-click the Payara server in Servers view, unfold the Publishing section, and select Automatically publish when resource change along with a low interval of like 0 seconds (see Figure 2-22).

Figure 2-22 Payara server configuration in Eclipse with automatic publishing enabled and interval set to 0 seconds

Now, save the web. xml and you’ll notice that Eclipse will immediately trigger Payara to publish the changes while still running. Coming back to the web browser, you’ll notice that the JSF page is now also accessible by just http://localhost:8080 (see Figure 2-23).

Figure 2-23 The Hello World page is now at the root

Configuring DataSource

In order to be able to interact with a SQL database, we need to configure a so-called data source in the web application project. This can be done by adding the following section to the web.xml:

<data-source>
    <name>java:global/DataSourceName</name>
    <class-name>org.h2.jdbcx.JdbcDataSource</class-name>
    <url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</url>
</data-source>

The data source name represents the JNDI (Java Naming and Directory Interface ) name. The class name represents the fully qualified name of the javax.sql.DataSource implementation of the JDBC driver being used. The URL represents the JDBC driver-specific URL format. The syntax is dependent on the JDBC driver being used. For an in-memory H2 database with a database name of “test,” that’s thus jdbc:h2:mem:test. The H2-specific DB_CLOSE_DELAY=-1 path parameter basically instructs its JDBC driver not to automatically shut down the database when it hasn’t been accessed for some time, even though the application server is still running.

A concrete instance of the DataSource can now be injected in any servlet container managed artifact such as a servlet or filter as follows:

@Resource
private DataSource dataSource;

You could get a SQL connection from it via DataSource#getConnection() for the plain old JDBC work. However, as we’re going to use Java EE, it’s better to use Java EE’s own JPA for this instead.

Configuring JPA

In order to familiarize JPA with the newly added data source, we need to add a new persistence unit to the persistence.xml which uses the data source as a JTA data source.

<persistence-unit name="PersistenceUnitName" transaction-type="JTA">
    <jta-data-source>java:global/DataSourceName</jta-data-source>

    <properties>
        <property
            name="javax.persistence.schema-generation.database.action"
            value="drop-and-create" />
    </properties>
</persistence-unit>

You see, the data source is identified by its JNDI name. You’ll also notice a JPA-specific javax.persistence.schema-generation.database.action property with a value of “drop-and-create” which basically means that the web application should automatically drop and create all SQL tables based on JPA entities. This is, of course, only useful for prototyping purposes, as we’re going to do with this project in the rest of the book. For real-world applications, you’d better pick either “create” or “none” (which is the default). The transaction type being set to “JTA” basically means that the application server should automatically manage database transactions. This way every method invocation on an EJB from its client (usually, a JSF backing bean) transparently starts a new transaction and when the EJB method returns to the client (usually, the calling backing bean), the transaction is automatically committed and flushed. And, any runtime exception from an EJB method automatically rolls back the transaction.

Creating the JPA Entity

Now we’re going to create a JPA entityc. Basically, it’s a JavaBean class which represents a single record of a database table. Each bean property is mapped to a particular column of the database table. Normally, JPA entities are modeled against existing database tables. But, as you’ve read in the previous section, “Configuring JPA,” about the persistence.xml, it’s also possible to do it the other way round: database tables are generated based on JPA entities.

Right-click the src/main/java folder of the project and choose New ➤ JPA Entity. In the wizard, set the Package to com.example.project.model and set the Name to Message. The rest of the fields can be kept default or empty (see Figure 2-24).

Figure 2-24 The New JPA Entity wizard in Eclipse

Modify the new entity class as follows:

package com.example.project.model;

import java.io.Serializable;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Lob;
import javax.validation.constraints.NotNull;

@Entity
public class Message implements Serializable {

    private static final long serialVersionUID = 1L;

    @Id @GeneratedValue(strategy=GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false) @Lob
    private @NotNull String text;

    // Add/generate getters and setters.
}

As a reminder, you can let Eclipse generate getters and setters by right-clicking anywhere in the class editor and choosing Source ➤ Generate Getters and Setters.

We'll briefly go through the annotations that are used here.

• @Entity—marks the bean as a JPA entity, so that the JPA implementation will automatically collect database-related metadata based on all its properties.

• @Id @GeneratedValue(strategy=IDENTITY)—marks a property to be mapped to a database column of SQL “IDENTITY” type. In MySQL terms, that’s the equivalent of “AUTO_INCREMENT”. In PostgreSQL terms, that’s the equivalent of “BIGSERIAL”.

• @Column—marks a property to be mapped to a regular database column. The actual database column type depends on the Java type being used. Without the additional @Lob annotation, that’s a VARCHAR(255) whose length can be manipulated by @Column(length=n). With the @Lob annotation, however, the column type becomes TEXT.

• @Lob—marks a String property to be mapped to a database column of type TEXT instead of a limited VARCHAR.

• @NotNull—this is actually not part of JPA but of “Bean Validation.” To the point, it ensures that the bean property is being validated never to be null when submitting a JSF form and when persisting the JPA entity. (See Chapter 5.) Also note that this basically replicates the @Column(nullable=false), but that’s only because JPA doesn’t consider any Bean Validation annotations as valid database metadata in order to generate appropriate SQL tables.

Creating the EJB Service

Next, we need to create an EJB in order to be able to save an instance of the aforementioned JPA entity in the database, and to obtain a list of JPA entities.

Right-click the src/main/java folder of the project and choose New ➤ Class. In the wizard, set the Package to com.example.project.service and set the Name to MessageService (see Figure 2-25). The rest of the fields can be kept default or empty.

Figure 2-25 The New Java Class wizard in Eclipse

Modify the new service class as follows:

package com.example.project.service;

import java.util.List;
import javax.ejb.Stateless;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;

@Stateless
public class MessageService {

    @PersistenceContext
    private EntityManager entityManager;

    public void create(Message message) {
        entityManager.persist(message);
    }

    public List<Message> list() {
        return entityManager
            .createQuery("FROM Message m", Message.class)
            .getResultList();
    }
}

That’s basically it. Let’s briefly go through the annotations .

• @Stateless—marks the bean as a stateless EJB service, so that the application server knows whether it should pool them and when to start and stop database transactions. The alternative annotations are @Stateful and @Singleton. Note that a @Stateless does not mean that the container will make sure that the class itself is stateless. You as developer are still responsible to ensure that the class doesn’t contain any shared and mutable instance variables. Otherwise, you’d better mark it as either @Stateful or @Singleton, depending on its purpose.

• @PersistenceContext—basically injects the JPA entity manager from the persistence unit as configured in the project’s persistence.xml. The entity manager is, in turn, responsible for mapping all JPA entities against a SQL database. It will, under cover, do all the hard JDBC work.

Adjusting the Hello World

Now we’re going to adjust the earlier created HelloWorld backing bean in order to save the messages in the database and display all of them in a table.

@Named @RequestScoped
public class HelloWorld {

    private Message message = new Message();
    private List<Message> messages;

    @Inject
    private MessageService messageService;

    @PostConstruct
    public void init() {
        messages = messageService.list();
    }

    public void submit() {
        messageService.create(message);
        messages.add(message);
    }

    public Message getMessage() {
        return message;
    }

    public List<Message> getMessages() {
        return messages;
    }
}

Note that you don’t need setters for message and messages. We’re going to use the getters and setters of the Message entity itself.

Finally, adjust the <h:body> of hello.xhtml as follows:

<h1>Hello World</h1>
<h:form>
    <h:outputLabel for="input" value="Input" />
    <h:inputText id="input" value="#{helloWorld.message.text}" />
    <h:commandButton value="Submit"
        action="#{helloWorld.submit}">
        <f:ajax execute="@form" render=":table" />
    </h:commandButton>
</h:form>
<h:dataTable id="table" value="#{helloWorld.messages}" var="message">
    <h:column>#{message.id}</h:column>
    <h:column>#{message.text}</h:column>
</h:dataTable>

Now reload the page in your favorite web browser and create some messages (see Figure 2-26).

Figure 2-26 The Hello World using JSF, CDI, EJB, and JPA