JSF 2.3 tutorial with Eclipse, Maven, WildFly and H2

Fast menu Introduction Installing Java SE JDK What About Jakarta EE? Installing WildFly Installing Eclipse Configuring Eclipse Integrating New Server in Eclipse Creating New Project in Eclipse Adjusting Deployment Descriptors Creating the Backing Bean Class Creating the Facelets File Deploying the Project Installing H2 Configuring DataSource Configuring JPA Creating the JPA Entity Creating the EJB Service Adjusting the Backing Bean and Facelet

Introduction

In this tutorial you will learn how to set up a JSF (Jakarta Faces) 2.3 development environment with the Eclipse IDE, the Maven dependency management system, the WildFly application server, and the H2 database from scratch.

Noted should be this tutorial was originally written by me for the “From Zero to Hello World” chapter of the book The Definitive Guide to JSF in Java EE 8, published at May 30, 2018. But as technology changes quickly, that chapter is currently slightly outdated. This tutorial is basically a rewrite of that chapter conform the current state of technology, 2 years later. Moreover, it covered Payara application server only while we’d like to use WildFly application server instead (whose JEE8 version wasn’t yet available at time of writing of the book, around Q4 of 2017).

Update March 2022: Also noted should be that there's already a newer version of the book available which among others helps setting up Jakarta Faces 4.0 from scratch: The Definitive Guide to Jakarta Faces in Jakarta EE 10, published at March 16, 2022.

Back to top

Installing Java SE JDK

You probably already know that Java SE is available as a JRE for end users and as a JDK for software developers. Eclipse itself does not strictly require a JDK as it has its own compiler. JSF being a software library does not require a JDK to run either. WildFly, however, does require a JDK to run, primarily in order to be able to compile JSP files, even though JSP has been deprecated as JSF view technology since JSF 2.0.

Therefore, you need to make sure that you already have a JDK installed as per Oracle’s instructions. The current Java SE version is 14, but as Jakarta EE 8 was designed for Java SE 8, you could get away with a minimum version of Java SE 8. Installation instructions depend on the platform being used (Windows, Linux, or macOS). You can find detailed Java SE 14 JDK installation instructions here.

The most important parts are that the PATH environment variable covers the /bin folder containing the Java executables (e.g., /path/to/jdk/bin), and that the JAVA_HOME environment variable is set to the JDK root folder (e.g., /path/to/jdk). This is not strictly required by JSF, but Eclipse and WildFly need this. Eclipse will need the PATH in order to find the Java executables. WildFly will need the JAVA_HOME in order to find the JDK tools.

Back to top

What About Jakarta EE?

First a small bit of history: “Java EE” has been renamed to “Jakarta EE” in February 2018, and the first Jakarta EE release, the Jakarta EE 8, became available in September 2019. So, anything related to “Java EE” is currently outdated. This includes the currently still available “Java EE SDK” download from Oracle.com. You should ignore that.

JSF itself is part of Jakarta EE. Jakarta EE is basically an abstract specification of which the so-­called application servers represent the concrete implementations. Examples of those application servers are Eclipse Glassfish, JBoss EAP, JEUS, Open Liberty, Payara Server, Primeton Appserver and WildFly. You can find them all at the Jakarta EE Compatible Products page. It are exactly those application servers that actually provide among others JSF, EL (Expression Language), JSTL (Jakarta Server Tag Library), CDI (Contexts and Dependency Injection), EJB (Enterprise JavaBeans), JPA (Java Persistence API), Servlet, WebSocket, and JSON-P APIs out of the box.

There also exist so-called servlet containers which provide basically only the Servlet, JASPIC, JSP, EL, and WebSocket APIs out of the box, such as Tomcat and Jetty. Therefore, it would require some work to manually install and configure among others JSF, JSTL, CDI, EJB, JPA and/or JSON-P on such a servlet container. It is not even trivial in the case of EJB as it basically 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. Note that TomEE is at the time of writing still not Jakarta EE compatible, so it’s not listed in the Jakarta EE Compatible Products page.

Back to top

Installing WildFly

WildFly is an open source Jakarta EE application server from Red Hat. You can download it from wildfly.org. Make sure you choose the “Jakarta EE 8 Full & Web Distribution" download and not, for example, the “WildFly Preview EE 9 Distribution” or “Servlet-Only Distribution”. It's available as WildFly versions 17.x until 26.x. We of course want the latest available one, so let's pick 26.1.3. Here’s a direct link to the ZIP file: 26.1.3.Final.

Installing is basically a matter of unzipping the downloaded file and putting it somewhere in your home folder. We’ll leave it there until we have Eclipse up and running, so that we can then integrate WildFly in Eclipse and let Eclipse manage the WildFly application server.

Back to top

Installing Eclipse

Eclipse is an open source IDE written in Java. You can download it from eclipse.org. It is basically like notepad but then with thousands if not millions of extra features, such as automatically compiling class files, building a WAR (Web Application Archive) file with them, and deploying it to an application server without the need to manually fiddle around with javac in a command console.

Eclipse is available in a lot of flavors, even for C/C++ and PHP. As we’re going to develop with Jakarta EE, we need the one saying “Eclipse IDE for Enterprise Java developers”, importantly the one with “Enterprise” in its name. The one without it doesn’t contain the mandatory plug-ins for developing Jakarta EE web applications. Here’s a direct link to the main download page of currently available latest version: 2023-12. In the section “Download Links” you can find platform-specific versions (Windows, Linux, or macOS).

Also here, installing is basically a matter of unzipping the downloaded file and putting it somewhere in your home folder.

In Windows and Linux you’ll find the eclipse.ini configuration file in the unzipped folder. In Mac OS this configuration file is located in Eclipse.app/Contents/Eclipse. Open this file for editing. We want to increase the allocated memory for Eclipse. At the bottom of eclipse.ini, you’ll find the following lines:

-Xms256m
-Xmx2048m

This sets, respectively, the initial and maximum memory size pool which Eclipse may use. This is a bit too low when you want to develop a bit decent Jakarta EE application. Let’s at least double both the values:

-Xms512m
-Xmx4g

Watch out that you don’t declare more than the available physical memory in the Xmx setting. When the actual memory usage exceeds the available physical memory, it will continue into virtual memory, usually in a swap file on disk. This will greatly decrease performance and result in major hiccups and slowdowns.

Now you can start Eclipse by executing the eclipse executable in the unzipped folder. You will be asked to select a directory as workspace. This is the directory where Eclipse will save all workspace projects and metadata.

After that, Eclipse will show a welcome screen. This is not interesting for now. You can click the Workbench button on the right top to close the welcome screen. Untick if necessary “Always show Welcome at start up” on the bottom right. After that, you will enter the workbench. By default, it looks like this:

Back to top

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 supports only 255 different characters and 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”. For more background information on character encodings, see my old but still very relevant blog article Unicode - How to get the characters right?
• 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 technical entries in XML configuration files such as faces-config.xml and web.xml for nothing, causing confusing warnings in those files such as “*.xhtml is not correctly spelled”.
• 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.
• Java ➤ Compiler ➤ Compiler compliance level must be set to at least 1.8. This is the minimum required Java version for Jakarta EE 8. You can of course also pick a higher version. For example 11 will work just fine. We’ll use that version in the remainder of this tutorial. It’s also going to be the minimum required Java version of the upcoming Jakarta EE 9.

Back to top

Integrating New Server in Eclipse

We need to familarize Eclipse with any installed application server so that Eclipse can seamlessly link its Jakarta 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 Jakarta EE API in your project. You know, the application server itself represents the concrete implementation of the abstract Jakarta 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.

Click the link which literally says “No servers are available. Click this link to create a new server...”. It’ll show the New Server wizard, displaying a list of available server types. From the list, select Red Hat JBoss Middleware ➤ JBoss AS, WildFly, & EAP Server Tools.

After clicking Next, it will download the plug-in in the backgroud and request you to accept the license agreement before installing the plug-in. This plug-in is mandatory in order to manage any JBoss server from inside the workbench. This will allow you to add and remove Eclipse projects to the deployments folder of the server, as well as starting and stopping the server, and running the server in debug mode.

Let it finish downloading and installing the plug-in in the background. Confirm any possible warning of “unsigned software”. This is okay. Finally 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 JBoss Community ➤ WildFly option.

Advance to the next step. Just leave this screen default.

Advance to the next step. Here, you should point the Home Directory field to the folder of the WildFly installation, there where you have unzipped it after downloading. And, you should adjust the Execution Environment to the desired JDK version. Pick JavaSE-11.

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.

Back to top

Creating New Project in Eclipse

We’re now ready to create a new project for our JSF application in Eclipse. This can be done via the left section of the workbench which by default shows only one tab representing the Project Explorer view (also here, you can add new views via Window ➤ Show View). By default, when there are no projects in your workspace, then it shows a list of options to create a new project. These options are also available via File ➤ New.

Eclipse, being an IDE for many different project tasks, offers a bewildering amount of different project types from which to choose. For a Jakarta EE-based application which is going to be deployed as a simple WAR file, there are basically two project types that we could choose from: Dynamic Web Project or Maven Project.

The difference is that the first is an Eclipse native project that really only works on Eclipse, while the latter is a universal type of project that can be built by any IDE, as well as easily on the command line and by various CI servers such as Travis and Jenkins. For this reason, the Maven project type is really the only viable choice.

In the next step, make sure that the option Create a simple project (skip archetype selection) is checked.

This will let us start with a really empty Maven project so that we can configure and populate it ourselves. Of course, you could also choose from an archetype, which is basically a template project with several already prepared files and configurations. But we don’t need any for now.

In the next step, we can specify our own Maven coordinates of the project. The Maven coordinates consist of, among others, Group Id, Artifact Id, and Version, also known as GAV in the Maven world. The Group Id usually matches the root package name you’re going to use, such as com.example. The Artifact Id usually represents the project name you’re going to use. For simplicity, we’ll use project. The Version can be kept default at 0.0.1-SNAPSHOT. Finally the Packaging must be set to war (Web Application Archive). This will during the build procude a WAR file instead of a JAR file.

Now click Finish. You don’t need to edit any other fields. Once you’ve finished the wizard, you’ll get to see the project structure in the Project Explorer view.

Unfortunately, the Eclipse-generated pom.xml, which is the main indicator of the project being a Maven project and containing its configuration, is less than ideal. It’s not current any more, even when generated by the latest Eclipse.

You can already see that by the pom.xml file being marked with an alarming red cross and an error message in the Markers view. Any project that has at least one such red cross cannot be built and won’t be deployable.

The error message literally says “web.xml is missing and <failOnMissingWebXml> is set to true.” In other words, Maven somehow thinks that it’s still a pre-Java EE 6 project, when this was indeed disallowed. In order to solve this problem and to catch up the Eclipse-generated pom.xml with the current standards, we need to open pom.xml for editing and adjust it to look exactly like follows:

<project
    xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
        http://maven.apache.org/xsd/maven-4.0.0.xsd"
>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>project</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>war</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </properties>

    <dependencies>
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-api</artifactId>
            <version>8.0.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

Once you save this file, Eclipse will automatically sort it out by itself and clear out the alarming red cross. Now that looks much better.

We’ll briefly go through the most important settings here.

• Packaging war — indicates the project is a “web” project, and that the project’s contents will be assembled into a WAR (Web Application Archive) file.
• Encoding UTF-8 — sets the encoding that the source files are in and with which the (reporting) output files should be generated. This makes the build repeatable, as it otherwise would default to the system default encoding.
• Compiler 11 — sets the version of Java SE used in the .java source files as well as the byte code output in the .class files. Without setting this, Maven defaults to the oldest version possible, and sometimes even a lower version than that.
• failOnMissingWebXml false — older versions of Java EE required the /WEB-INF/web.xml file to be physically present in the WAR project. Even though this has not been required any more since Java EE 6, which was released in 2009, Maven still checks for this file to be present. Setting this to false prevents this unnecessary check.
• Dependency jakarta.platform:jakarta.jakartaee-api:8.0.0:provided — this declares a dependency on the Jakarta EE 8 API, and makes sure all the Jakarta EE types like FacesServlet, @Named and @Entity are known to the compiler. This dependency is set to provided since those types are in our case already provided by the target runtime, which is WildFly 18, a Jakarta EE 8 compatible application server. This dependency will then only be used to compile the source code against, and the associated JAR files won’t be included in the generated WAR file. You need to make absolutely sure that any compile time dependency which is already provided by the target runtime is set to provided; otherwise it will eventually end up in the generated WAR file and you may run into class loading trouble wherein duplicate different versioned libraries are conflicting with each other. In case you’re actually not targeting a full-fledged Jakarta EE server but a barebones servlet container, such as Tomcat, then you would need to adjust the dependencies as instructed in the installation instructions of Mojarra, one of the available JSF implementations and actually the one used under the covers of WildFly.

Now, in Eclipse’s Markers view, there are two warnings left which say “The compiler compliance specified is 1.5 but a JRE 14 is used” and “Build path specifies execution environment J2SE-1.5. There are no JREs installed in the workspace that are strictly compatible with this environment”. Well, this basically means that Eclipse recognizes this Maven project as a Java SE 1.5-only project while we don’t actually have Java SE 5 installed, and in spite of the compiler version in pom.xml being set to 11. This is an Eclipse+Maven quirk. Eclipse clearly knows how to find the configured compiler version in pom.xml, but unfortunately refuses to automatically adjust its project settings based on that.

In order to tell Eclipse that this is really a Java SE 11 targeted project, we need to right-click the project in Project Explorer view and choose Properties. In the Project Facets section you should change the version of the “Java” entry from 1.5 to 11 (or whatever compiler version specified in pom.xml).

While at it, we also need to update the Servlet API version and add the JSF and JPA facets. The Servlet API is represented by the “Dynamic Web Module” entry. This needs to be set to version 4.0, which matches Jakarta EE 8. Further the “JavaServer Faces” and “JPA” entries need to be selected.

As you can see in the yellow warning bar, Eclipse requires further configuration. This concerns the newly selected JSF and JPA facets. Click the link. We get to see the Modify Faceted Project wizard.

The first step of the Modify Faceted Project wizard allows us to configure the JPA facet. We need to make sure that Eclipse is being instructed that the JPA implementation is already provided by the target runtime and thus Eclipse doesn’t need to include any libraries. This can be achieved by choosing the “Disable Library Configuration” option in the JPA implementation field.

As we’re going to use the WildFly-provided Hibernate as the actual JPA implementation, which supports automatically discovering of @Entity annotated classes, we’d like to instruct Eclipse to do the same. So, choose the “Discover annotated classes automatically” option in the Persistent class management field. Otherwise Eclipse would automatically add entities to the persistence.xml file when going through the entity code generation wizards, or it would show warnings when we manually create one and don’t add it to the persistence.xml.

Note that configuring a database connection (for Eclipse’s built-in data explorer) is not necessary for now as we’re going to use an embedded database.

In the next step of the Modify Faceted Project wizard, we can configure the JSF capabilities. Also here, we need to make sure that Eclipse is being instructed that the JSF implementation is already provided by the target runtime and thus Eclipse doesn’t need to include any libraries. This can be achieved by choosing the “Disable Library Configuration” option in the JSF Implementation Library field.

Further, we need to rename the servlet name of the FacesServlet to match the fictive instance variable name: facesServlet. Last but not least, we absolutely need to change the URL mapping pattern from the jurassic /faces/* to the modern *.xhtml.

Actually, the entire registration of the FacesServlet in web.xml is since JSF 2.2 not strictly necessary any more; you could even uncheck the Configure JSF servlet in deployment descriptor option and rely on the default auto-registered mappings of /faces/*, *.faces, *.jsf and *.xhtml. However, as this allows endusers and even searchbots to open the very same JSF page by different URLs, and thus causes confusion among endusers and duplicate content penalties among searchbots, we’d better restrict to only one explicitly configured URL pattern of *.xhtml. For more background information on JSF URL patterns, see also this Stack Overflow post.

Now, finish and apply all the wizards and dialogs.

Unfortunately, the JPA plug-in of the current Eclipse version only puts the generated persistence.xml in the wrong place. It’s basically not being aware of the project being a Maven-based WAR project and Eclipse’s JPA plug-in blindly puts it in the src/main/java/META-INF folder as if it were a JAR project. This is wrong. You need to manually move it into src/main/resources/META-INF folder conform the rules of a Maven-based WAR project. The workbench must now look like as follows:

Back to top

Adjusting Deployment Descriptors

We only need to verify and adjust all the deployment descriptors to catch up to the Servlet, JSF, JPA, and CDI versions actually used by the target runtime. This is normally done by editing the root element of the deployment descriptor XML file to set the desired version attribute along with version-specific XML schema definitions (XSDs).

You can find all Jakarta EE 8 XSDs at http://xmlns.jcp.org/xml/ns/javaee, which is an actual web page which currently redirects to some landing page at Oracle.com. This may change in the future given that Jakarta EE 8 is currently in the process of being transferred from Oracle to Eclipse, and moreover the javaee part may in the future even be renamed. At this landing page, click the “Java EE 8 Schema Resources” link to see a list of the correct XSD versions. Yes, the Java EE 8 XSDs are still appplicable to Jakarta EE 8.

You can open the deployment descriptor XML file for editing by double-clicking it in the Project Explorer and then selecting the Source tab in the editor. The correct root element declarations for Jakarta EE 8 compatible deployment descriptors are thus as follows:

1. src/main/webapp/WEB-INF/web.xml for Servlet 4.0:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="4.0"
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
        http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
>
    <!-- Servlet configuration here. -->
</web-app>

Make sure that the FacesServlet as we created in the Modify Faceted Project wizard is indeed there and that it’s indeed mapped on an URL pattern of *.xhtml.

Unfortunately, the currently available Eclipse version might annoyingly freeze for ~15 seconds during saving the web.xml file when its xsi:schemalocation references XSD file of version 4.0. This is caused by Eclipse Bug 534776. There is so far no clear work around yet. You could only remove the xsi:schemalocation attribute to avoid this from happening. The disadvantage of removing this is that the contents of the web.xml file cannot anymore be autocompleted during typing, nor be validated by Eclipse, and thus e.g. typos may slip through.

2. src/main/webapp/WEB-INF/faces-config.xml for JSF 2.3:

<?xml version="1.0" encoding="UTF-8"?>
<faces-config version="2.3"
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
        http://xmlns.jcp.org/xml/ns/javaee/web-facesconfig_2_3.xsd"
>
    <!-- JSF configuration here. -->
</faces-config>

As of now it’s indeed empty.

3. src/main/resources/META-INF/persistence.xml for JPA 2.2:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.2"
    xmlns="http://xmlns.jcp.org/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
        http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
>
    <!-- JPA configuration here. -->
</persistence>

As of it indeed only contains the default persistence unit. We’ll reconfigure it later on.

4. src/main/webapp/WEB-INF/beans.xml for CDI 2.0:

For sake of completeness we need to manually create one more deployment descriptor file, the one for CDI 2.0. This isn’t automatically generated as it’s not required. CDI is by default always enabled in any Jakarta EE 8 compatible web application. It’s even mandatory for the functioning of JSF. Among others the new <f:websocket> relies fully on CDI for tracking the opened web sockets.

Right-click the WEB-INF folder of the project and choose New ➤ File. Give it the name beans.xml. Populate the new file as follows:

<?xml version="1.0" encoding="UTF-8"?>
<beans version="2.0" bean-discovery-mode="annotated"
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
        http://xmlns.jcp.org/xml/ns/javaee/beans_2_0.xsd"
>
    <!-- CDI configuration here. -->
</beans>

Note that the bean-discovery-mode is set to annotated. This is the default value. The other value is all. This is slightly more intrusive and expensive as it will consider any Java class as a potential CDI bean.

Back to top

Configuring JSF

JSF has a lot of settings available which can be configured via <context-param> entries in web.xml. You can find an overview of them in this Stack Overflow post.

The default configuration is okay to start with, but there’s one peculiar setting which we really want to set right from the beginning on. It’s the setting which instructs JSF whether to interpret empty string submitted values as null. Elaborate background information can be found in my another blog article The empty String madness.

This can be done by adding the following section to top of the web.xml:

<context-param>
    <param-name>javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL</param-name>
    <param-value>true</param-value>
</context-param>

Back to top

Creating the Backing Bean Class

With the project now correctly configured we can finally 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 ➤ Class. The New Java Class wizard will now appear. In this wizard, set the Package to com.example.project.view, set the Name to Bean. The rest of the fields can be kept default or empty.

The class editor will now open with the newly created backing bean class. We’ll modify it to add CDI @Named and @RequestScoped annotations on the class, so that it becomes a CDI managed bean. And we need to add two properties, input and output, and accompany the input property with a getter and setter pair, the output property with only a getter, so that these can be referenced from the view. Finally we’ll add a submit() action method which prepares the output property based on the input property, so that this can be invoked from the view.

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 Bean {

    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 in the view. Without any attributes this name defaults to the simple class name with the first letter in lowercase, thus “bean” here. It will be available by #{bean} in EL. This can be used in JSF pages.
• @RequestScoped — gives the bean a scope, which means that the same instance of the bean is used throughout the given lifespan. In the case of @RequestScoped that lifespan is the duration of an HTTP request. When the scope ends, then the bean is automatically destroyed. There are more scopes available, such as @ViewScoped, @SessionScoped and @ApplicationScoped. You can read more about scopes in this Stack Overflow post.

Back to top

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”. When the FacesServlet is invoked with an URL matching the path of this Facelets file, then JSF will ultimately parse it and generate the HTML markup that is sent to the browser as a response to the 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 ➤ File. Give it the name test.xhtml.

The HTML editor will now open with 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="#{bean.input}" />
            <h:commandButton value="Submit" action="#{bean.submit}">
                <f:ajax execute="@form" render=":output" />
            </h:commandButton>
        </h:form>
        <h:outputText id="output" value="#{bean.output}" />
    </h:body>
</html>

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

• <h:head> — generates the HTML <head> element. 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> element. You can also use a plain HTML <body> in this specific Facelet example, 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> element. JSF will automatically include the so-called view state in a hidden input field within the form.
• <h:outputLabel> — generates the HTML <label> element. 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"> element. 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"> element. JSF will automatically invoke the bean method specified in the action attribute.
• <f:ajax> — generates the necessary JavaScript code to enable Ajax behavior of the tag it is being nested in, in this case thus the <h:commandButton>. You can also do as good without it, but then the form submit won’t be performed asynchronously. The execute attribute of @form indicates that the entire <h:form> where it is sitting in must be processed on submit, and the render attribute of :output indicates that the tag identified by id="output" must be automatically updated on complete of the Ajax submit. For more background information on the syntax of the execute and render attributes, see this Stack Overflow post.
• <h:outputText> — generates the HTML <span> element. 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”. 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 more easily achievable with them.

Noted should be that a HTML5 doctype is indeed explicitly being used “in spite of” that it’s a XHTML file. HTML5 is these days the standard for web pages. For more background information on this, see this Stack Overflow post.

Back to top

Deploying the Project

In the Servers view, right-click the WildFly server entry and choose Add and Remove. It will show the Add and Remove wizard 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.

Now start the WildFly 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 tooltip 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.

Now, open a tab in your favorite web browser and enter the web address http://localhost:8080/project-0.0.1-SNAPSHOT/test.xhtml in order to open the newly created JSF page. Play a bit around with it.

Coming back to the URL, the “localhost:8080” part is by convention the default domain of any Jakarta EE server which is running in development mode. The same address is also used by, among others, Payara and TomEE. The “/project-0.0.1-SNAPSHOT” part is by default the filename of the Maven-generated WAR file. In case of WildFly, you can find it in its /standalone/deployments folder. This part is in Servlet terms called the “context path” and obtainable by HttpServletRequest#getContextPath() and in JSF delegated by ExternalContext#getRequestContextPath().

If you have hard time in figuring out the actually used context path, then you can usually find it in the server logs. The exact logger line is however dependent on the server being used. In case of WildFly, it’ll be the line identified by WFLYUT0021. Open the Console view, press Ctrl+F and search for WFLYUT0021. It’ll show the following line:

INFO  [org.wildfly.extension.undertow] (ServerService Thread Pool -- 42) WFLYUT0021: Registered web context: '/project-0.0.1-SNAPSHOT' for server 'default-server'

The context path part can also be set to “/”. The deployed web application will then end up in the domain root. How to do that depends on the server being used. In case of WildFly, you’ll need to create the JBoss-specific jboss-web.xml as follows:

src/main/webapp/WEB-INF/jboss-web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jboss-web PUBLIC
    "-//JBoss//DTD JBOSS 5.0//EN"
    "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd"
>
<jboss-web>
    <context-root>/</context-root>
</jboss-web>

Now it will be deployed to the domain root and after restarting the server you can access the JSF page by http://localhost:8080/test.xhtml.

We can even get a step further by making test.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 bottom of web.xml:

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

This will basically instruct the server to use the specified file within the folder as default resource when any folder is requested. So, if for example / folder is requested, then it’ll search for a /test.xhtml and serve it. Or if for example /foo folder is requested, then it’ll search for a /foo/test.xhtml and serve it. Etcetera. Now, save the web.xml and restart the server.

Coming back to the web browser, you’ll notice that the JSF page is now also accessible by merely http://localhost:8080.

Back to top

Installing H2

H2 is an in-memory SQL database. It’s an embedded database useful for quickly modeling and testing JPA entities, certainly in combination with autogenerated SQL tables based on JPA entities. Adding H2 to your web application project is a matter of adding the following dependency to the <dependencies> section of the pom.xml file:

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>1.4.200</version>
</dependency>

That’s basically it. Its JDBC (Java Database Connecivity) driver is also provided by this dependency.

Back to top

Configuring DataSource

In order to be able to interact with any 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>

It basically creates a connection pooled data source in the server itself. The data source <name> represents the JNDI (Java Naming and Directory Interface) name. The “java:global/” part is mandatory. The DataSourceName is free to your choice. It’s the one that ultimately needs to be registered in persistence.xml later on. 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. Usually the syntax can be found in the JDBC driver specific documentation. 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.

After configuring the data source, a concrete instance of the javax.sql.DataSource can now be injected in any servlet container managed artifact such as a plain vanilla 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 pure Jakarta EE, it’s better to use Jakarta EE’s own JPA for this instead.

Back to top

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 which we confgured earlier in web.xml.

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 basically doing in this tutorial. 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. For more information on usefulness of this, see also this Stack Overflow post.

Back to top

Creating the JPA Entity

Now we’re going to create a JPA entity. 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. This is not recommended for production applications, but it’s useful for prototyping as we’re basically doing in this tutorial.

Right-click the src/main/java folder of the project and choose New ➤ JPA Entity. In the wizard, set the Java package to com.example.project.model and set the Class name to Message. The rest of the fields can be kept default or empty.

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 SQL database column of “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 SQL database column. The actual SQL database column type depends on the Java type being used. In case of a Java String, without the additional @Lob annotation, that’s by default a VARCHAR(255) whose length can be manipulated by ­ @Column(length=n). With the @Lob annotation present, however, the SQL database column type becomes by default TEXT.
• @Lob — marks a String property to be mapped to a SQL 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. 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.

Back to top

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 them from the database. 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. The rest of the fields can be kept default or empty.

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;

import com.example.project.model.Message;

@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. See also this Stack Overflow post.
• @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 the covers, do all the hard JDBC work.

Back to top

Adjusting the Backing Bean and Facelet

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

package com.example.project.view;

import java.util.List;

import javax.annotation.PostConstruct;
import javax.enterprise.context.RequestScoped;
import javax.inject.Inject;
import javax.inject.Named;

import com.example.project.model.Message;
import com.example.project.service.MessageService;

@Named @RequestScoped
public class Bean {

    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);
        message = new Message();
    }
    
    public Message getMessage() {
        return message;
    }
    
    public List<Message> getMessages() {
        return messages;
    }
}

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

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

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

Now, restart the server, reload the page in your favorite web browser and create some messages.

As a reminder, the in-memory H2 database will be emptied when you restart the server. If you want to “avoid” this, simply switch to a real database, such as PostgreSQL or MySQL.

That's it! Hopefully it's helpful to get started with JSF 2.3 in Jakarta EE. If you want to explore further, advance to my Stack Overflow answers. You can find a collection of "most valuable" answers at https://jsf.zeef.com/bauke.scholtz. If you already have a moderate knowledge on web application development in general, and want to greatly expand your JSF knowledge, then consider picking the book The Definitive Guide to JSF in Java EE 8. Apart from the “From Zero to Hello World” chapter, the rest of the book is still very up to date these days.

Back to top

Copyright - None of this article may be taken over without explicit authorisation.

(C) April 2020, BalusC