-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Automated publish
committed
Sep 5, 2024
1 parent
aecbbc1
commit 3387305
Showing
25 changed files
with
354 additions
and
1,333 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,352 @@ | ||
| <!DOCTYPE html> | ||
|
|
||
|
|
||
| <!-- | ||
| | Generated by Apache Maven Doxia Site Renderer 2.0.0-M19 from src/site/markdown/coreprofile/create_a_json_rest_service.md at 2024-09-05 | ||
| | Rendered using Apache Maven Fluido Skin 2.0.0-M10 | ||
| --> | ||
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> | ||
| <head> | ||
| <meta charset="UTF-8" /> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1" /> | ||
| <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M19" /> | ||
| <title>Create a JSON REST service – Piranha</title> | ||
| <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M10.min.css" /> | ||
| <link rel="stylesheet" href="../css/site.css" /> | ||
| <link rel="stylesheet" href="../css/print.css" media="print" /> | ||
| <script src="../js/apache-maven-fluido-2.0.0-M10.min.js"></script> | ||
| <style>.github-fork-ribbon:before { background-color: black; }</style> | ||
| </head> | ||
| <body> | ||
| <a class="github-fork-ribbon right-bottom fixed" href="https://github.com/piranhacloud/piranha" data-ribbon="Fork me on GitHub">Fork me on GitHub</a> | ||
| <div class="container-fluid container-fluid-top"> | ||
| <header> | ||
| <div id="banner"> | ||
| <div class="pull-left"></div> | ||
| <div class="pull-right"></div> | ||
| <div class="clear"><hr/></div> | ||
| </div> | ||
|
|
||
| <div id="breadcrumbs"> | ||
| <ul class="breadcrumb"> | ||
| <li id="projectVersion">Version: 24.9.0-SNAPSHOT</li> | ||
| <li id="publishDate" class="pull-right">Last Published: 2024-09-05</li> | ||
| </ul> | ||
| </div> | ||
| </header> | ||
| <div class="row-fluid"> | ||
| <header id="leftColumn" class="span2"> | ||
| <nav class="well sidebar-nav"> | ||
| <ul class="nav nav-list"> | ||
| <li class="nav-header">Overview</li> | ||
| <li><a href="../getting-started.html">Getting Started</a></li> | ||
| </ul> | ||
| </nav> | ||
| <div class="well sidebar-nav"> | ||
| <div id="poweredBy"> | ||
| <div class="clear"></div> | ||
| <div id="twitter" style="border:none; margin-top: 10px"> | ||
| <a href="https://twitter.com/piranha_cloud" class="twitter-follow-button" data-show-count="false" data-align="left" data-size="medium" data-show-screen-name="false" data-lang="en" data-dnt="true" >Follow piranha_cloud</a> | ||
| <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> | ||
| </div> | ||
| <div class="clear"></div> | ||
| <a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> | ||
| </div> | ||
| </div> | ||
| </header> | ||
| <main id="bodyColumn" class="span10"> | ||
| <section><a id="Create_a_JSON_REST_service"></a> | ||
| <h1>Create a JSON REST service</h1> | ||
| <p>If you are looking to create a JSON based REST service with Piranha then | ||
| consider Piranha Core Profile. It features a runtime ideally suited for REST, | ||
| JSON and micro services.</p> | ||
| <p>In 7 steps you will learn how to create the JSON REST service. They are:</p> | ||
| <ol style="list-style-type: decimal;"> | ||
|
|
||
| <li>Create the Maven POM file</li> | ||
| <li>Add the application class</li> | ||
| <li>Add the POJO class</li> | ||
| <li>Add the endpoint</li> | ||
| <li>Add an integration test</li> | ||
| <li>Test the application</li> | ||
| <li>Deploy the application</li> | ||
| </ol><section><a id="Create_the_Maven_POM_file"></a> | ||
| <h2>Create the Maven POM file</h2> | ||
| <p>Create an empty directory to store your Maven project. Inside of that directory create the <code>pom.xml</code> file with the content as below.</p> | ||
|
|
||
| <pre class="prettyprint"><code class="language-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>json</artifactId> | ||
| <version>1-SNAPSHOT</version> | ||
| <packaging>war</packaging> | ||
| <name>Piranha Core Profile - Temperature JSON 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>temperature</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> | ||
| </code></pre></section><section><a id="Add_the_application_class"></a> | ||
| <h2>Add the application class</h2> | ||
| <p>Add the Application class in the <code>src/main/java</code> directory, which allows you to | ||
| set the application path using the @ApplicationPath annotation.</p> | ||
|
|
||
| <pre class="prettyprint"><code class="language-java">package temperature; | ||
|
|
||
| import jakarta.ws.rs.ApplicationPath; | ||
| import jakarta.ws.rs.core.Application; | ||
|
|
||
| @ApplicationPath("") | ||
| public class TemperatureApplication extends Application { | ||
| } | ||
| </code></pre></section><section><a id="Add_the_POJO"></a> | ||
| <h2>Add the POJO</h2> | ||
| <p>As we are going to be returning JSON in the endpoint we need a POJO to represent | ||
| the model. Add the POJO class in the <code>src/main/java</code> directory.</p> | ||
|
|
||
| <pre class="prettyprint"><code class="language-java">package temperature; | ||
|
|
||
| public class Temperature { | ||
|
|
||
| public enum TemperatureScale { | ||
| CELSIUS, | ||
| FAHRENHEIT | ||
| } | ||
|
|
||
| private TemperatureScale scale; | ||
|
|
||
| private double temperature; | ||
|
|
||
| public TemperatureScale getScale() { | ||
| return scale; | ||
| } | ||
|
|
||
| public double getTemperature() { | ||
| return temperature; | ||
| } | ||
|
|
||
| public void setScale(TemperatureScale scale) { | ||
| this.scale = scale; | ||
| } | ||
|
|
||
| public void setTemperature(double temperature) { | ||
| this.temperature = temperature; | ||
| } | ||
| } | ||
| </code></pre></section><section><a id="Add_the_endpoint"></a> | ||
| <h2>Add the endpoint</h2> | ||
| <p>And the next step is creating the class with the <code>celsius</code> and <code>fahrenheit</code> | ||
| endpoints.</p> | ||
|
|
||
| <pre class="prettyprint"><code class="language-java">package temperature; | ||
|
|
||
| import jakarta.enterprise.context.RequestScoped; | ||
| import jakarta.ws.rs.GET; | ||
| import jakarta.ws.rs.Path; | ||
| import jakarta.ws.rs.PathParam; | ||
| import jakarta.ws.rs.Produces; | ||
| import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON; | ||
| import static temperature.Temperature.TemperatureScale.CELSIUS; | ||
| import static temperature.Temperature.TemperatureScale.FAHRENHEIT; | ||
|
|
||
| @RequestScoped | ||
| @Path("") | ||
| public class TemperatureBean { | ||
|
|
||
| @GET | ||
| @Produces(APPLICATION_JSON) | ||
| @Path("/celsius/{celsius}") | ||
| public Temperature celsius(@PathParam("celsius") double celsius) { | ||
| Temperature temp = new Temperature(); | ||
| temp.setScale(CELSIUS); | ||
| temp.setTemperature(celsius); | ||
| return temp; | ||
| } | ||
|
|
||
| @GET | ||
| @Produces("application/json") | ||
| @Path("/fahrenheit/{fahrenheit}") | ||
| public Temperature fahrenheit(@PathParam("fahrenheit") double fahrenheit) { | ||
| Temperature temp = new Temperature(); | ||
| temp.setScale(FAHRENHEIT); | ||
| temp.setTemperature(fahrenheit); | ||
| return temp; | ||
| } | ||
| } | ||
| </code></pre></section><section><a id="Add_an_integration_test"></a> | ||
| <h2>Add an integration test</h2> | ||
| <p>As we want to make sure the application gets tested before we release 2 | ||
| integration tests are added which will be executed as part of the build.</p> | ||
| <p>We'll add the 2 integration tests to the <code>src/test/java</code> directory.</p> | ||
|
|
||
| <pre class="prettyprint"><code class="language-java">package temperature; | ||
|
|
||
| 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.assertEquals; | ||
| import org.junit.jupiter.api.Test; | ||
|
|
||
| class TemperatureIT { | ||
|
|
||
| @Test | ||
| void testCelsius() throws Exception { | ||
| HttpClient client = HttpClient.newHttpClient(); | ||
| HttpRequest request = HttpRequest | ||
| .newBuilder(new URI("http://localhost:8080/temperature/celsius/18.5")) | ||
| .build(); | ||
| HttpResponse<String> response = client.send(request, BodyHandlers.ofString()); | ||
| assertEquals("{\"scale\":\"CELSIUS\",\"temperature\":18.5}", response.body()); | ||
| } | ||
|
|
||
| @Test | ||
| void testFahrenheit() throws Exception { | ||
| HttpClient client = HttpClient.newHttpClient(); | ||
| HttpRequest request = HttpRequest | ||
| .newBuilder(new URI("http://localhost:8080/temperature/fahrenheit/68.0")) | ||
| .build(); | ||
| HttpResponse<String> response = client.send(request, BodyHandlers.ofString()); | ||
| assertEquals("{\"scale\":\"FAHRENHEIT\",\"temperature\":68.0}", response.body()); | ||
| } | ||
| } | ||
| </code></pre></section><section><a id="Test_the_application"></a> | ||
| <h2>Test the application</h2> | ||
| <p>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.</p> | ||
| <p>To build and test the application execute the following command:</p> | ||
|
|
||
| <pre class="prettyprint"><code class="language-bash"> mvn install | ||
| </code></pre></section><section><a id="Deploy_the_application"></a> | ||
| <h2>Deploy the application</h2> | ||
| <p>To deploy your application you will need 2 pieces.</p> | ||
| <ol style="list-style-type: decimal;"> | ||
|
|
||
| <li>The Piranha Core Profile runtime JAR.</li> | ||
| <li>The WAR file you just produced.</li> | ||
| </ol> | ||
| <p>For the WAR file see the <code>target</code> directory. For the Piranha Core Profile | ||
| distribution go to Maven Central. And then the following command line will | ||
| deploy your application:</p> | ||
|
|
||
| <pre class="prettyprint"><code class="language-bash"> java -jar piranha-dist-coreprofile.jar --war-file json.war | ||
| </code></pre></section><section><a id="Conclusion"></a> | ||
| <h2>Conclusion</h2> | ||
| <p>As illustrated, creating a JSON based REST service with Piranha Core Profile is | ||
| pretty straightforward because of the libaries available to you as part of the | ||
| Jakarta EE Core Profile.</p></section><section><a id="References"></a> | ||
| <h2>References</h2> | ||
| <ol style="list-style-type: decimal;"> | ||
|
|
||
| <li><a href="index.html">Piranha Core Profile</a></li> | ||
| <li><a href="../maven-plugin/index.html">Piranha Maven plugin documentation</a></li> | ||
| </ol> | ||
| <p><a href="index.html">Up</a></p></section></section> </main> | ||
| </div> | ||
| </div> | ||
| <hr/> | ||
| <footer> | ||
| <div class="container-fluid"> | ||
| <div class="row-fluid"> | ||
| <p class="pull-right">© 2024 | ||
| <a href="https://piranha.cloud">Piranha Cloud</a> | ||
| </p> | ||
| </div> | ||
| </div> | ||
| </footer> | ||
| </body> | ||
| </html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.