@@ -4,12 +4,10 @@ This repository contains the code base of a sample project that will be used in
...
@@ -4,12 +4,10 @@ This repository contains the code base of a sample project that will be used in
the XCS subject inside the DGSS itinerary.
the XCS subject inside the DGSS itinerary.
## 1. Deployment Environment
## 1. Deployment Environment
The environment is based on Java 8, Maven 3.3+, Git 1.9+, MySQL 8+,
The environment is based on Java 8, Maven 3.3+, Git 1.9+, MySQL 8+, WildFly 10.1.0 and Eclipse IDE for Enterprise Java and Web Developers.
WildFly 10.1.0 and Eclipse for JavaEE.
### 1.1. Java JDK 8
### 1.1. Java JDK 8
Download and install Java JDK 8, preferably the Oracle version (the commands
Download and install Java JDK 8 (the commands `java` and `javac` must be available).
`java` and `javac` must be available).
You can test your Java installation with the commands:
You can test your Java installation with the commands:
...
@@ -19,9 +17,7 @@ javac -version
...
@@ -19,9 +17,7 @@ javac -version
```
```
### 1.2. Maven 3.3+
### 1.2. Maven 3.3+
Install Maven 3 in your system, if it was not installed (the `mvn` command must
Install Maven 3 in your system, if it was not installed (the `mvn` command must be available). If you are in a Debian-based OS, install the `maven` package (**don't install `maven2` package!!**):
be available). If you are in a Debian-based OS, install the `maven` package
(**don't install `maven2` package!!**):
```
```
sudo apt-get install maven
sudo apt-get install maven
...
@@ -34,10 +30,7 @@ mvn --version
...
@@ -34,10 +30,7 @@ mvn --version
```
```
### 1.3. Git 1.9+
### 1.3. Git 1.9+
Firstly, install Git in your system if it was not installed (the `git` command
Firstly, install Git in your system if it was not installed (the `git` command must be available). We will work with Git to get updates of these sample. Concretely, we will work with a Git repository inside [our Gitlab server](https://www.sing-group.org/dt/gitlab).
must be available). We will work with Git to get updates of these sample.
Concretely, we will work with a Git repository inside
In order to run the tests with the `wildfly-embedded-mysql` profile (more about
In order to run the tests with the `wildfly-embedded-mysql` profile (more about this in the **Sample 2** section) and to run the application, we need a MySQL server.
this in the **Sample 2** section) and to run the application, we need a MySQL
server.
The server can be installed as usual, but it must contain two databases:
The server can be installed as usual, but it must contain two databases:
* The `xcs` database for running the application.
* The `xcs` database for running the application.
* The `xcssampletest` database for testing the appliaction.
* The `xcssampletest` database for testing the appliaction.
In both cases, the user `xcs` identified by `xcs` password should have all
In both cases, the user `xcs` identified by `xcs` password should have all privileges on this database. You can do this by executing the following commands:
privileges on this database. You can do this by executing the following
commands:
```sql
```sql
CREATEDATABASExcs;
CREATEDATABASExcs;
...
@@ -75,9 +64,7 @@ GRANT ALL PRIVILEGES ON xcssampletest.* TO xcs@'%';
...
@@ -75,9 +64,7 @@ GRANT ALL PRIVILEGES ON xcssampletest.* TO xcs@'%';
FLUSHPRIVILEGES;
FLUSHPRIVILEGES;
```
```
If you want to add some data to the `xcs` database to run the application (data
If you want to add some data to the `xcs` database to run the application (data will be automatically inserted to the `xcssampletest` database during the tests) you can also execute:
will be automatically inserted to the `xcssampletest` database during the
You can find the `xcs-sample-mysql.sql` and `xcs-sample-test-mysql.sql` scripts
You can find the `xcs-sample-mysql.sql` and `xcs-sample-test-mysql.sql` scripts with these queries stored in the `additional-material/db` project folder.
with these queries stored in the `additional-material/db` project folder.
### 1.5. Eclipse for Java EE
### 1.5. Eclipse for Java EE
Open Eclipse for Java EE and import your Maven project with
Open Eclipse for Java EE and import your Maven project with `File -> Import -> Maven -> Existing Maven Projects`. In the dialog opened you have to select as `Root directory` the directory of the project that you have just cloned (it should contain a `pom.xml` file).
`File -> Import -> Maven -> Existing Maven Projects`. In the dialog opened you
have to select as `Root directory` the directory of the project that you have
Eclipse should then import a parent project (`xcs-sample`) and 6 child projects (`tests`, `domain`, `service`, `rest`, `jsf` and `ear`). If any project is disabled for import it is probably because you already have another project in your workspace with the same name. To avoid this problem you can open the advanced settings of the dialog and use a custom `Name template` (for example, `xcs-sample-[artifactId]`).
just cloned (it should contain a `pom.xml` file).
If you want, you can use any other IDE, such as IntelliJ IDEA or NetBeans, as long as they are compatible with Maven projects, but we recommend using Eclipse for Java EE.
Eclipse should then import a parent project (`xcs-sample`) and 6 child projects
(`tests`, `domain`, `service`, `rest`, `jsf` and `ear`). If any project is
disabled for import it is probably because you already have another project in
your workspace with the same name. To avoid this problem you can open the
advanced settings of the dialog and use a custom `Name template` (for example,
`xcs-sample-[artifactId]`).
If you want, you can use any other IDE, such as IntelliJ IDEA or NetBeans, as
long as they are compatible with Maven projects, but we recommend using Eclipse
for Java EE.
### 1.6 WildFly 10.1.0
### 1.6 WildFly 10.1.0
If you want to run the project you need a Java EE server. In this section you
If you want to run the project you need a Java EE server. In this section you can find how to configure a local WildFly server to execute the project. Basically, we need to configure the WildFly server to include the datasource and the security configuration needed by the application.
can find how to configure a local WildFly server to execute the project.
Basically, we need to configure the WildFly server to include the datasource and
In the following sections you can find an explanation of how you can configure the WildFly server by editing the `standalone.xml`. However, the `additional-material/wildfly` directory of the project already includes a `standalone.xml` ready to be used with the 10.1.0 version, that you can just copy directly into your WildFly server (replacing the original
the security configuration needed by the application.
In the following sections you can find an explanation of how you can configure
the WildFly server by editing the `standalone.xml`. However, the
`additional-material/wildfly` directory of the project already includes a
`standalone.xml` ready to be used with the 10.1.0 version, that you can
just copy directly into your WildFly server (replacing the original
`standalone/configuration/standalone.xml` file).
`standalone/configuration/standalone.xml` file).
#### 1.6.1. Datasource configuration
#### 1.6.1. Datasource configuration
There are several ways to add a datasource to a WildFly server. We are going to
There are several ways to add a datasource to a WildFly server. We are going to add it by editing the `standalone/configuration/standalone.xml` configuration file of the server. To do so, you have to edit this file and add the following content to the `<datasources>` element:
add it by editing the `standalone/configuration/standalone.xml` configuration
file of the server. To do so, you have to edit this file and add the following
@@ -167,14 +133,11 @@ content to the `<datasources>` element:
...
@@ -167,14 +133,11 @@ content to the `<datasources>` element:
</datasource>
</datasource>
```
```
In addition, you also have to add the MySQL driver to the deployments folder
In addition, you also have to add the MySQL driver to the deployments folder (`standalone/deployments`). You can download it form [here](https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.1.0/mysql-connector-j-8.1.0.jar) to the deployments (`standalone/deployments`) directory and WildFly will
(`standalone/deployments`). You can download it form [here](http://central.maven.org/maven2/mysql/mysql-connector-java/8.0.21/mysql-connector-java-8.0.21.jar)
to the deployments (`standalone/deployments`) directory and WildFly will
automatically deploy it on startup.
automatically deploy it on startup.
#### 1.6.2. Security configuration
#### 1.6.2. Security configuration
All the WildFly security configuration is done in the
All the WildFly security configuration is done in the `standalone/configuration/standalone.xml` file of the server.
`standalone/configuration/standalone.xml` file of the server.
Inside the `<security-reamls>` element you have to add a new security realm:
Inside the `<security-reamls>` element you have to add a new security realm:
...
@@ -186,8 +149,7 @@ Inside the `<security-reamls>` element you have to add a new security realm:
...
@@ -186,8 +149,7 @@ Inside the `<security-reamls>` element you have to add a new security realm:
</security-realm>
</security-realm>
```
```
Then, inside the `<security-domains>` element you have to add the following
Then, inside the `<security-domains>` element you have to add the following security domains:
When the `package` goal is run in the `xcs-sample` project, an EAR file is
When the `package` goal is run in the `xcs-sample` project, an EAR file is generated inside the `target` folder of the `ear` project.
generated inside the `target` folder of the `ear` project.
The EAR file contains all the elements of the project (JARs and WARs) and,
The EAR file contains all the elements of the project (JARs and WARs) and, therefore, you only have to deploy this file in the WildFly container to deploy the entire application. To do so, you can copy this file to the `standalone/deployments` folder of WidlFly.
therefore, you only have to deploy this file in the WildFly container to deploy
the entire application. To do so, you can copy this file to the
`standalone/deployments` folder of WidlFly.
Once this is done, you can run the WildFly server executing the
Once this is done, you can run the WildFly server executing the `bin/standalone.sh` script. The application should be running in http://localhost:8080/xcs-sample. If you want to access through the web interface, you can open the http://localhost:8080/xcs-sample/jsf URL.
`bin/standalone.sh` script. The application should be running in
http://localhost:8080/xcs-sample. If you want to access through the web
interface, you can open the http://localhost:8080/xcs-sample/jsf URL.
#### 1.6.4 Deploying the application from Maven
#### 1.6.4 Deploying the application from Maven
Maven configuration is prepared to deploy the generated EAR file to a running
Maven configuration is prepared to deploy the generated EAR file to a running WildFly. Doing so is as easy as launching the `wildfly:deploy` goal:
WildFly. Doing so is as easy as launching the `wildfly:deploy` goal:
```bash
```bash
mvn wildfly:deploy
mvn wildfly:deploy
```
```
This will launch the construction of the project and, at the end, the EAR will
This will launch the construction of the project and, at the end, the EAR will be deployed. Remember that, if you want a fast deployment, you can avoid the test execution with the parameter `-DskipTests=true`.
be deployed. Remember that, if you want a fast deployment, you can avoid the
test execution with the parameter `-DskipTests=true`.
#### 1.7. Running the application from Maven (Recommended)
#### 1.7. Running the application from Maven (Recommended)
This project includes the Maven WildFly plugin, which allows the execution of
This project includes the Maven WildFly plugin, which allows the execution of the application without needing an external WildFly server. To run the application with the running MySQL database (`xcs`) you just have execute the following command:
the application without needing an external WildFly server. To run the
application with the running MySQL database (`xcs`) you just have execute the
This will launch the complete construction cycle without running the tests,
This will launch the complete construction cycle without running the tests, start a WildFly server and deploy the application. Once the application is running you can access it in the URL http://localhost:8080/xcs-sample/jsf.
start a WildFly server and deploy the application. Once the application is
running you can access it in the URL http://localhost:8080/xcs-sample/jsf.
**Important**: You shouldn't have a local WildFly instance running or Maven will
**Important**: You shouldn't have a local WildFly instance running or Maven will not be able to start its own WildFly and will try to deploy the application in the running instance. This will cause changes to the WildFly configuration that may leave it in an unstable state.
not be able to start its own WildFly and will try to deploy the application in
the running instance. This will cause changes to the WildFly configuration that
may leave it in an unstable state.
To stop the WildFly launched you can execute the following command:
To stop the WildFly launched you can execute the following command:
...
@@ -263,62 +207,38 @@ mvn wildfly:shutdown
...
@@ -263,62 +207,38 @@ mvn wildfly:shutdown
## 2. Samples
## 2. Samples
## 2.1. Sample 1: Testing entities
## 2.1. Sample 1: Testing entities
Using JUnit and Hamcrest, we will see how to test JPA entities or any other
Using JUnit and Hamcrest, we will see how to test JPA entities or any other Java class. This libraries are the base for every test done in the application.
Java class. This libraries are the base for every test done in the application.
## 2.2. Sample 2: Testing EJBs
## 2.2. Sample 2: Testing EJBs
Using Arquillian and Arquillian Persistence, the EJBs are tested. We wouldn't do
Using Arquillian and Arquillian Persistence, the EJBs are tested. We wouldn't do unit testing in this layer, as we don't want to mock the `EntityManager`.
unit testing in this layer, as we don't want to mock the `EntityManager`.
In this layer we will use some workarounds to set the desired role and principal
In this layer we will use some workarounds to set the desired role and principal in the tests.
in the tests.
### 2.2.1. How to run tests with Arquillian?
### 2.2.1. How to run tests with Arquillian?
This project is configured to use two Maven profiles:
This project is configured to use two Maven profiles:
*`wildfly-embedded-h2`: this profile uses WildFly in embedded mode with a H2
*`wildfly-embedded-h2`: this profile uses WildFly in embedded mode with a H2 database, whose driver is included by default in WilFly.
database, whose driver is included by default in WilFly.
*`wildfly-embedded-mysql`: same as before, but it uses a MySQL database.
*`wildfly-embedded-mysql`: same as before, but it uses a MySQL database.
In both profiles, the WildFly server is automatically downloaded using the
In both profiles, the WildFly server is automatically downloaded using the `maven-dependency-plugin`, that extracts it in the `target/wildfly-<version>` folder (`target/wildfly-10.1.0.Final` currently). In the MySQL profile, the MySQL driver is also downloaded using this plugin and added to the `target/wildfly-<version>/standalone/deployments` folder, to make it available in the WildFly server.
`maven-dependency-plugin`, that extracts it in the `target/wildfly-<version>`
folder (`target/wildfly-10.1.0.Final` currently). In the MySQL profile, the
MySQL driver is also downloaded using this plugin and added to the
`target/wildfly-<version>/standalone/deployments` folder, to make it available
in the WildFly server.
For each profile, Maven is configured to use the files stored in
For each profile, Maven is configured to use the files stored in `src/test/resources-<profile name>` as resources when running tests, in addition to the stored in the `src/test/resources` folder, as usual. Inside this folder, the projects using Arquillian must include a `standalone.xml` file, that will be replace the default `standalone.xml` file of the WildFly server. This is specially useful to configure the security constraints and datasources.
`src/test/resources-<profile name>` as resources when running tests, in addition
to the stored in the `src/test/resources` folder, as usual. Inside this folder,
the projects using Arquillian must include a `standalone.xml` file, that will be
replace the default `standalone.xml` file of the WildFly server. This is
specially useful to configure the security constraints and datasources.
In order to avoid port collising with other WildFly instances, the WildFly used
In order to avoid port collising with other WildFly instances, the WildFly used by the test have a port offset of 10000. This means that the HTTP port is displaced from the default 8080 port to the 18080 port, and the management port is displaced from the default 9990 port to the 19990 port.
by the test have a port offset of 10000. This means that the HTTP port is
displaced from the default 8080 port to the 18080 port, and the management port
is displaced from the default 9990 port to the 19990 port.
Therefore, when running Maven tests (e.g. `mvn test`), they will run without any
Therefore, when running Maven tests (e.g. `mvn test`), they will run without any external requirement.
external requirement.
#### 2.2.1.1 Arquillian tests in Eclipse
#### 2.2.1.1 Arquillian tests in Eclipse
To run Arquillian tests in Eclipse (or in any non-Maven enviroment) a further
To run Arquillian tests in Eclipse (or in any non-Maven enviroment) a further step is needed. You must configure the following system properties:
step is needed. You must configure the following system properties:
*`arquillian.launch`: the launch configuration that arquillian should use.
*`arquillian.launch`: the launch configuration that arquillian should use.
*`wildfly.version`: the version of the WildFly server stored in `target`.
*`wildfly.version`: the version of the WildFly server stored in `target`. The current version is `10.1.0.Final`.
The current version is `10.1.0.Final`.
*`wildfly.jbossHome`: the location of the WildFly server.
*`wildfly.jbossHome`: the location of the WildFly server.
*`wildfly.modulePath`: the location of the module of the WildFly server.
*`wildfly.modulePath`: the location of the module of the WildFly server.
*`java.util.logging.manager`: the logger to be used by the standard Java
*`java.util.logging.manager`: the logger to be used by the standard Java logger. Commonly, the value `org.jboss.logmanager.LogManager` is used.
logger. Commonly, the value `org.jboss.logmanager.LogManager` is used.
*`jboss.socket.binding.port-offset`: this is an optional parameter that can be used to move the WildFly default ports.
*`jboss.socket.binding.port-offset`: this is an optional parameter that
can be used to move the WildFly default ports.
*`wildfly.http.port`: HTTP of the WildFly server.
*`wildfly.http.port`: HTTP of the WildFly server.
*`wildfly.management.port`: management port of the WildFly server.
*`wildfly.management.port`: management port of the WildFly server.
In Eclipse, this system properties can be added to the run configuration in the
In Eclipse, this system properties can be added to the run configuration in the `VM arguments` field of the `Arguments` tab. For example, the following configuration will work for the current configuration:
`VM arguments` field of the `Arguments` tab. For example, the following
configuration will work for the current configuration:
```
```
-Darquillian.launch=wildfly-embedded
-Darquillian.launch=wildfly-embedded
...
@@ -331,17 +251,14 @@ configuration will work for the current configuration:
...
@@ -331,17 +251,14 @@ configuration will work for the current configuration:
-Dwildfly.management.port=19990
-Dwildfly.management.port=19990
```
```
This configuration will run with the **H2** database. If you wish to run the
This configuration will run with the **H2** database. If you wish to run the tests with the **MySQL** database, you have to add to additional system configuration:
tests with the **MySQL** database, you have to add to additional system
*`mysql.version`: The version of the MySQL driver (currently, `8.1.0`)
configuration:
*`mysql.version`: The version of the MySQL driver (currently, `8.0.21`).
Therefore, the `VM arguments` configuration for running the tests in Eclipse
Therefore, the `VM arguments` configuration for running the tests in Eclipse using the MySQL database is:
<spanstyle="color:red">Warning: </span>JSF test have been disabled due to a [known connection issue](https://firefox-source-docs.mozilla.org/testing/geckodriver/Usage.html#Running-Firefox-in-an-container-based-package) between the Firefox driver and the Firefox installed by default in Ubuntu
22.04.
## 2.6. Sample 6: Additional Testing Tools
## 2.6. Sample 6: Additional Testing Tools
### Test coverage with JaCoCo
### Test coverage with JaCoCo
Test coverage is a very useful tool that shows the parts of the source code that
Test coverage is a very useful tool that shows the parts of the source code that are covered by the tests. The coverage analysis is done during the tests execution, making it very precise.
are covered by the tests. The coverage analysis is done during the tests
execution, making it very precise.
The JaCoCo plugin is now part or the project, analyzing the test execution. This
The JaCoCo plugin is now part or the project, analyzing the test execution. This plugin generates a HTML report in the `target/site/jacoco` folder. This report is very useful to check if some part of the code is missing some tests.
plugin generates a HTML report in the `target/site/jacoco` folder. This report
is very useful to check if some part of the code is missing some tests.