Skip to content

Commit

Permalink
Fixes #3909 - Migrate Piranha Core Profile - Create a REST service to…
Browse files Browse the repository at this point in the history 
… docs from Piranha Website repository (#3910)
  • Loading branch information
@mnriem
mnriem authored Sep 6, 2024
1 parent a6220f3 commit bac642d
Show file tree
Hide file tree
Showing 4 changed files with 229 additions and 1 deletion.
226 changes: 226 additions & 0 deletions docs/src/site/markdown/coreprofile/create_a_rest_service.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,226 @@
# Create a REST service

If you are looking to create a REST service with Piranha then consider Piranha Core Profile. It features a runtime ideally suited for REST and micro services.

In 6 steps you will learn how to create the REST service. They are:

1. Create the Maven POM file
1. Add the application class
1. Add the endpoint
1. Add an integration test
1. Test the application
1. 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
<?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.coreprofile</groupId>
<artifactId>rest</artifactId>
<version>1-SNAPSHOT</version>
<packaging>war</packaging>
<name>Piranha Core Profile - REST 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.version>23.6.0</piranha.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-core-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>
</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.

```java
package rest;

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("")
public class RestApplication extends Application {
}
```

## Add the endpoint

And we are adding a simple 'Hello World' endpoint that is listening on the `/helloworld` path.

```java
package rest;

import jakarta.enterprise.context.RequestScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/helloworld")
@RequestScoped
public class HelloWorldBean {

@GET
public String helloWorld() {
return "Hello World!";
}
}
```

## 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.

```java
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 HelloWorldIT {

@Test
void testHelloWorld() throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest
.newBuilder(new URI("http://localhost:8080/rest/helloworld"))
.build();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
assertTrue(response.body().contains("Hello World!"));
}
}

```

## 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:

```bash
mvn install
```

## Deploy the application

To deploy your application you will need 2 pieces.

1. The Piranha Core Profile runtime JAR.
2. The WAR file you just produced.

For the WAR file see the `target` directory. For the Piranha Core Profile distribution go to Maven Central. And then the following command line will deploy your application:

```bash
java -jar piranha-dist-coreprofile.jar --war-file rest.war
```

## Conclusion

As you can see getting started with Piranha Core Profile does not have to take long.

## References

1. [Piranha Core Profile](index.html)
1. [Piranha Maven plugin documentation](../maven-plugin/index.html)

[Up](index.html)
1 change: 1 addition & 0 deletions docs/src/site/markdown/coreprofile/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ The following components are available in the Piranha Core Profile distribution:

## Documentation

1. [Create a REST service](create_a_rest_service.html)
1. [Create a JSON REST service](create_a_json_rest_service.html)
1. [Jakarta EE 10 Core Profile Specification](https://jakarta.ee/specifications/coreprofile/10/jakarta-coreprofile-spec-10.0.pdf)
1. [Jakarta EE 10 Core Profile API documentation](https://jakarta.ee/specifications/coreprofile/10/apidocs/)
Expand Down
1 change: 1 addition & 0 deletions docs/src/site/site.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
</menu>
<menu name="Piranha Core Profile">
<item name="Overview" href="coreprofile/index.html"/>
<item name="Create a REST service" href="coreprofile/create_a_rest_service.html"/>
<item name="Create a JSON REST service" href="coreprofile/create_a_json_rest_service.html"/>
</menu>
</body>
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -530,7 +530,7 @@
<configuration>
<rules>
<requireMavenVersion>
<version>3.8.7</version>
<version>3.8.8</version>
</requireMavenVersion>
<requireJavaVersion>
<version>${java.version}</version>
Expand Down

0 comments on commit bac642d

Please sign in to comment.