Setup JSF 2.3 and JPA Project with Payara in IntelliJ

Created: 24.03.2019

In this article, I will show you step by step how to setup a JSF 2.3 project in IntelliJ and run it on a local Payara application server.

Tl;dr

If the text is too long for you, you can have a look at my video :)

Step 1: Download Payara and Dependencies

Before you start, you will need the Payara application server. You can find the download page here. The server comes in two flavors:

  • Full Profile: Most Java 8 EE libraries, including REST-API.
  • Web Profile (outdated): Selected Java 8 EE libraries for Servlet/JSP/JSF applications.
  • Micro Profile: Minimal profile with little overhead (and convenience) functions.

I usually go with the full profile as it contains most of the libraries I need for JSF applications.

Step 1a: Put Global Libraries to Payara lib Folder

If you want to use a database that is not supported out-of-the-box, you need to provide the JDBC driver. This can be done in various ways. I like to add it directly to the server's lib folder as it is then available for all applications.

The folder is located in: <PAYARA_ROOT_DIRECTORY>/payara5/glassfish/lib

In case you use MySQL be aware that since the upgrade to version 8
some driver names changed.

Step 1b: Download Primefaces or any other Library

I personally love Primefaces. As IntelliJ typically has not the latest version of Primefaces, I download it myself and integrate it later as self-provided library.

Just make sure that you have the jar somewhere on your hard disk.

Step 2: Setup IntelliJ Project

Create a new project in IntelliJ. First, make sure that you have a Java JDK (not JRE) on your system and linked to this project as most application servers need the JDK to run.

Then select the Java Enterprise framework "JSF" and your favorite library. I personally love Primefaces, that is why I added a tutorial how to integrate the latest version.

At this point, I create my custom Primefaces library to have the latest version.

Next, setup JavaEE Persistence. Payara comes with a bundled EclipseLink, so you can select EclipseLink as provider and "Setup library later". On a sidenote, every application server comes with a different JPA setup. TomEE, for example, has OpenJPA as provider.

Step 3: Cleanup Library and Project Setup

First, I would like to enable Maven support. Select the project and right click > "Add Framework Support". Then select Maven.

Select the project and hit File > Project Structure. We will go through each setting one by one starting with "Modules".

Navigate to the tab "Dependencies" and check if the Glassfish Libraries are on "provided". In addition, the Primefaces Library should show up as compile dependency.

In the standard JSF setting, there is a provided JSF implementation library. You can remove it as the Payara server contains his own library. Do so in the "Libraries" section.

Under "Facets" make sure that the "Web Facet" is configured correctly. It consists of the deployment descriptor (web.xml) and the folder that contains all your XHTML documents. It should also point to the correct java source folders.

Finally and most important, check the Artifacts section. In this section, the bundling is configured and this needs to be done right, if you do not bundle with Maven.

  • Select type of artifact "Web Application: Exploded". Exploded means that you can see the contents of the war instead of a single zip file. This is much easier for debugging purposes.
  • Put everything in the "Available Elements" section via double click in the bundled artifact. That includes
    • The primefaces library.
    • Any custom Maven library.
    • The JPA descriptor (persistence.xml).

If everything is correctly set, you should see you generated artifact during the next deployment in the folder "out" or "target" (depending on Maven nature).

Step 4: Start the Admin Console

Before you can start the server, you need to add at least one Handler class in your source folder otherwise you probably get an Exception "CDI Bean not found". I know, that is fucked up, right? It took me ages to figure that out. On a side note, you might also get "CDI Bean not found" if you have multiple JSF implementations in your classpath.

Select your project and then hit Run > Edit Configurations. You first need to add your Payara server (if not done already in the application server setting).

Next, configure your server. For now, the domain is enough. The default domain is called "domain1".

Finally, go to the tab "Deployment". You need to register all the applications that you want to deploy on this server.

You can now start the server by hitting Run > Run Server or the little triangle button in the lower left corner.

When you start the server, you see that actually two listeners were created. Navigate to the admin console via browser.

  • http://localhost:4848 for the admin console
  • http://localhost:8080 for the application server

Step 5: Setup JTA Datasource

In the admin console, you will configure your database. You have two options in JPA to define database connections:

  • Resource local: This one is rather for desktop applications. You can specify a persistence unit with connection string like you would when using JDBC directly.
  • Java Transaction API (JTA): This one is recommended. You specify the database connection in the application server. The application server provides a link to the database connection via JNDI.

For JSF applications JTA is actually required (I'm pretty sure that there are some workarounds though).

Create you connection pool depending on the type of database. I am using MySQL in version 8.

The driver name changed from MySQL 5,6 to 8.

Sometimes you will be presented with just a few attributes to set. In my case, I get around 200 attributes. All you have to set is user, password, URL and url (yes, you need to set it twice to be sure).

If everything is specified correctly, you can perform a ping to test the connection.

Finally, you just need to set the JDBC resource that is basically a named link to a connection of a certain connection pool.

Step 6: Run the Project

At this point, you are almost set to go. Now, you need to adjust the persistence.xml.

<?xml version="1.0" encoding="UTF-8"?>
	<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="2.0">
		<persistence-unit name="PU" transaction-type="JTA">
            <jta-data-source>jdbc/rvm</jta-data-source>
            <properties>
                <property name="eclipselink.ddl-generation" value="create-or-extend-tables" />
                <property name="eclipselink.ddl-generation.output-mode" value="database" />
            </properties>
		</persistence-unit>
</persistence>

Check out my other articles, if you want to learn more about using the EntityManager.

In a sample page, you can refer to the primefaces namespace:

<?xml version="1.0" encoding="UTF-8"?>  
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"          
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:h="http://xmlns.jcp.org/jsf/html"
    xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
    xmlns:f="http://xmlns.jcp.org/jsf/core"
    xmlns:jsf="http://xmlns.jcp.org/jsf"
    xmlns:p="http://primefaces.org/ui">  
<h:head></h:head>  
	<h:body>      
		<h:outputLabel value="Hello World" />      
		<p:spinner />  
	</h:body>  
</html>

Congrats, if you reached this point and your project is running.