Create a Jakarta REST service
This guide illustrates how you can create a Jakarta REST service with Piranha Web Profile.
In 6 steps you will learn how to create the REST service. They are:
- Create the Maven POM file
- Add the application class
- Add the endpoint
- Add an integration test
- Test the application
- Deploy the application
Create the Maven POM file
Create an empty directory to store your Maven project. Inside of that directory create the pom.xml
file with the content as below.
<?xml version="1.0" encoding="UTF-8"?>
<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>cloud.piranha.guides.webprofile</groupId>
<artifactId>rest</artifactId>
<version>1-SNAPSHOT</version>
<packaging>war</packaging>
<name>Piranha Web Profile - HelloREST service</name>
<properties>
<jakartaee.version>10.0.0</jakartaee.version>
<java.version>17</java.version>
<junit.version>5.10.0-M1</junit.version>
<maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
<maven-failsafe-plugin.version>3.0.0</maven-failsafe-plugin.version>
<maven-war-plugin.version>3.3.2</maven-war-plugin.version>
<piranha.distribution>webprofile</piranha.distribution>
<piranha.version>23.6.0</piranha.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-web-api</artifactId>
<version>${jakartaee.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-params</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<finalName>rest</finalName>
<plugins>
<plugin>
<groupId>cloud.piranha.maven.plugins</groupId>
<artifactId>piranha-maven-plugin</artifactId>
<version>${piranha.version}</version>
<executions>
<execution>
<id>pre-integration-test</id>
<phase>pre-integration-test</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-integration-test</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
<configuration>
<distribution>${piranha.distribution}</distribution>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven-compiler-plugin.version}</version>
<configuration>
<release>${java.version}</release>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${maven-failsafe-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>${maven-war-plugin.version}</version>
<configuration>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
</plugins>
</build>
</project>
Add the application class
Add the Application class in the src/main/java
directory, which allows you to
set the application path using the @ApplicationPath annotation.
package rest;
import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;
@ApplicationPath("")
public class HelloRestApplication extends Application {
}
Add the endpoint
And we are adding a simple ‘Hello REST!’ endpoint that is listening on the
/hellorest
path.
package rest;
import jakarta.enterprise.context.RequestScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
@RequestScoped
@Path("/hellorest")
public class HelloRestBean {
@GET
public String hello() {
return "Hello REST!";
}
}
Add an integration test
As we want to make sure the application gets tested before we release an integration test is added which will be executed as part of the build.
We'll add the integration test to the src/test/java
directory.
package rest;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import static org.junit.jupiter.api.Assertions.assertTrue;
import org.junit.jupiter.api.Test;
class HelloRestIT {
@Test
void testHelloWorld() throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest
.newBuilder(new URI("http://localhost:8080/rest/hellorest"))
.build();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
assertTrue(response.body().contains("Hello REST!"));
}
}
Test the application
The application is setup to use JUnit to do integration testing using the Piranha Maven plugin so when you are building the application it will also execute an integration test validating the endpoint works.
To build and test the application execute the following command:
mvn install
Deploy the application
To deploy your application you will need 2 pieces.
- The Piranha Core Profile runtime JAR.
- The WAR file you just produced.
For the WAR file see the target
directory. For the Piranha WEb Profile
distribution go to Maven Central. And then the following command line will
deploy your application:
java -jar piranha-dist-webprofile.jar --war-file rest.war
Conclusion
As you can see getting started with Piranha Web Profile to create a REST service is pretty easy.