Tutorial00

JButler has moved!

The new version of JButler is now hosted at Labes/UFES and there is a new tutorial as well. This repository contains an older version, if you're interested.

---

Welcome to the tutorial "Jakarta EE Web Profile application with JButler". In this tutorial, we start from scratch and give step-by-step instructions on how to use many of the features present in JButler.

The running example for this tutorial is Oldenburg, a system which helps professors teaching Research Methodology courses to simulate a workshop in which the students will submit papers and perform peer review. The application is named after Henry Oldenburg which, according to Wikipedia, is the creator of scientific peer review. If you're using this tutorial to bootstrap your own Web application, you should replace all references to Oldenburg with your application's name throughout the tutorial.

Tool installation and configuration

The following tools and versions were used in this tutorial (newer versions of these tools might also work the same way):

Technology	Tool	Version	Download
Java SDK	OpenJDK	13	jdk.java.net
IDE	Eclipse	2020-12	eclipse.org
Database System	MySQL Community Server	8.0	dev.mysql.com
Database Front-end	MySQL Workbench	8.0	dev.mysql.com
JDBC Driver	MySQL Connector/J	8.0	dev.mysql.com
Jakarta EE Server	WildFly	22.0.1	wildfly.org

Installation instructions vary according to operating system (Linux, MacOS or Windows), therefore we have not included detailed, step-by-step instructions on how to install these tools. Recently, Eclipse started providing an installer with a step-by-step process, in which you should choose Eclipse IDE for Enterprise Java Developers. For WildFly it's enough to unpack them somewhere in your hard drive. We'll refer to the folder where Eclipse was installed and you unpacked WildFly as $ECLIPSE_HOME and $WILDFLY_HOME, respectively. The JDK and the MySQL server and workbench can be installed using an install wizard downloaded from their website or through your system's package manager (e.g.: apt-get in Ubuntu Linux or any other Debian-based distributions). Finally, the Connector/J driver will be used during WildFly's configuration.

Set-up Eclipse to work with WildFly

To deploy our application in WildFly during development more easily, it's recommended to integrate the IDE Eclipse with the application server WildFly. This is done with some tools provided by JBoss/Red Hat, which can now be installed in a more straightforward way in the latest Eclipse version:

1. Open Eclipse;
2. Click at the menu Help > Eclipse Marketplace...;
3. In the Find: field, type JBoss and click Go;
4. Locate JBoss Tools 4.18.0.Final (or a more recent version) and click Install, then Confirm >, select I accept the terms of the license agreements and click Finish. Wait for installation and restart Eclipse afterwards;
5. Open the Servers view (if not visible, use the Window > Show View menu);
6. Click on the "No servers are available. Click this link to create a new server..." link, which is shown when the Servers view is empty. Alternatively, right-click the blank space at the Servers view and select New > Server;
7. Under JBoss Community folder, select WildFly 22. Click Next twice;
8. Fill in the server's directory (pointing it to $WILDFLY_HOME, whatever that is in your system) and click Finish.

At the end of the wizard, the WildFly server should be at the Servers view. Right-clicking on it allows you to start, stop, restart the server. Try starting the server and if everything is OK you should see as the last message in the Console view something like shown below. Then open http://localhost:8080/ and you should see WildFly's welcome page.

INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: WildFly Full 22.0.1.Final (WildFly Core 14.0.1.Final) started in 7008ms - Started 318 of 557 services (345 services are lazy, passive or on-demand)

Set-up WildFly to connect to MySQL

WildFly comes with an H2 Database driver configured. In this tutorial, however, we use MySQL, so we need to add its driver to WildFly's configuration. Follow these steps to do it (make sure the server is stopped for this):

1. In the folder $WILDFLY_HOME/modules, create the following directory structure: com/mysql/main (we are using / to separate sub-directories; Windows users should replace it with \);

2. Unpack the MySQL Connector/J JDBC Driver you downloaded earlier and copy the file mysql-connector-java-8.0.23.jar to the newly created folder $WILDFLY_HOME/modules/com/mysql/main. If you downloaded a different version of Connector/J, adjust the name accordingly;

3. Still at $WILDFLY_HOME/modules/com/mysql/main, create a file named module.xml with the following contents (again if you downloaded a different version of Connector/J, adjust the name accordingly):

   <?xml version="1.0" encoding="UTF-8"?>
   <module xmlns="urn:jboss:module:1.1" name="com.mysql">
   	<resources>
   		<resource-root path="mysql-connector-java-8.0.23.jar"/>
   	</resources>
   	<dependencies>
   		<module name="javax.api"/>
   	</dependencies>
   </module>

4. In Eclipse's Servers view, make sure WildFly is not running, then look for WildFly 22/Filesets/Configuration File/standalone.xml and open this file. Using the Source tab, look for the tag <subsystem xmlns="urn:jboss:domain:datasources:6.0">. Inside this tag, locate <datasources> and then <drivers>. You should find the H2 Database driver configuration there. Next to it, add the configuration for MySQL Connector/J, as following:

   <driver name="mysql" module="com.mysql">
   	<driver-class>com.mysql.cj.jdbc.Driver</driver-class>
   </driver>

You should now be ready to develop a Jakarta EE project in Eclipse, deploying it in WildFly and configuring it to use MySQL database for persistence. The above steps need to be done just once for all projects which will use these tools.

Database creation and set-up

We will use JPA (Java Persistence API), one of the Jakarta EE standards, persisting our objects in a relational database stored in the MySQL server. We will, therefore:

1. Create a database schema named oldenburg;
2. Create a database user named dwws with password dwws;
3. Give user dwws full permission for the schema oldenburg.

(For all example applications that I develop during the Web Development and the Semantic Web course I teach --- whose acronym, in Portuguese, is DWWS --- I use the same database user dwws. You can use whatever username and password suits you best, as long as you configure the datasource later with the same credentials.)

To do that, use MySQL Workbench. Once you open it, connect to the server using the root user (the administrator) and you should see a screen similar to the figure below (it's from an older version, so you might need to adapt a bit). If you see an error message at the bottom of the screen indicating that a connection to the server could not be established, click on Server > Startup/Shutdown and click the button to start the server.

To create the database, click the Create a new schema button in the toolbar, indicated by the red arrow in the above figure. Fill in oldenburg as Schema Name and select utf8mb4 as Character Set. Finally, click Apply and then Apply again to create the database schema.

Next, click on Users and Privileges at the left-hand side of the Workbench's window and the Administration - Users and Privileges tab should open (see figure below). Click on the Add Account button and fill in the dwws user information like shown in the figure below (the password, which is hidden in the figure, should be dwws as well):

Click Apply and then switch to the Schema Privileges section of the user details (see figure below). Click the Add Entry button, choose the Selected schema radio button and select oldenburg at the list of schemas. Click OK to go back to the Schema Privileges screen, click the Select "ALL" button to give the dwws user all the necessary permissions over the oldenburg schema and, finally, click Apply. The schema privileges configuration should end up like shown in the figure below:

You can now close MySQL Workbench.

Datasource configuration in WildFly

While we could configure JPA to connect to the database we have just created in a configuration file in our project, creating a datasource for it in WildFly allows us to use JTA (Java Transaction API), another standard from Jakarta EE, which provides us with automatic transaction management.

To create a JTA datasource for Oldenburg in WildFly, again open the standalone.xml file and look for the tag <subsystem xmlns="urn:jboss:domain:datasources:6.0">. Inside this tag, there is a <datasources> tag which holds the configuration for the java:jboss/datasources/ExampleDS datasource that WildFly comes with. Next to it, add a datasource for the oldenburg database in MySQL:

<datasource jta="true" jndi-name="java:jboss/datasources/Oldenburg" pool-name="OldenburgPool" enabled="true" use-java-context="true">
    <connection-url>jdbc:mysql://localhost:3306/oldenburg</connection-url>
    <driver>mysql</driver>
    <security>
        <user-name>dwws</user-name>
        <password>dwws</password>
    </security>
</datasource>

If you have SSL problems connecting to the MySQL database with Connector/J, try to append ?useSSL=false to the connection URL. (Thanks Claudenir for the tip!).

It's a good idea, at this point, to test if the MySQL driver and the data source were properly configured in WildFly. To do this, start the server from within Eclipse's Servers view and verify that the console outputs no errors or exceptions. Instead, you should see messages similar to these (... indicates other messages in between):

INFO  [org.jboss.modules] (main) JBoss Modules version 1.11.0.Final
...
INFO  [org.jboss.as.connector.deployers.jdbc] (MSC service thread 1-6) WFLYJCA0018: Started Driver service with driver-name = mysql
...
INFO  [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-1) WFLYJCA0001: Bound data source [java:jboss/datasources/Oldenburg]
...
INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: WildFly Full 22.0.1.Final (WildFly Core 14.0.1.Final) started in 5907ms - Started 326 of 565 services (346 services are lazy, passive or on-demand)

Next: create a new Web project