It is summer time, and that means warm weather, swimming pools, and ice cold drinks. In this post, I will demonstrate how to develop a simple microservices-based application using Jakarta RESTful Web Services to provide the data for the application. Did you know that there is an easy way to get started with Jakarta EE using the Jakarta EE Starter project? In this post, I will demonstrate how to utilize the starter. First, we need to mix up a drink to enjoy while we code! If you'd prefer to skip the cocktail and code without it, then please skip to the "Time to Code" section below.
Let's Mix a Cocktail - Classic Margarita Recipe
While you could go to a store and purchase a pre-mixed margarita, those mixes are rarely as good as a classic margarita made from scratch. I prefer my margaritas on-the-rocks (ice cubes), although it is also popular to have a frozen margarita, which is more of an icy concoction similar to a slush. Whatever your preference, this classic recipe will work. Let's get mixing!
What you'll need:
– 2 fluid ounces of blanco tequila (higher quality is better)
– 1 1/2 fluid ounces of triple sec (higher quality is better)
– 1 ounce of lime juice (fresh is best)
– 1 1/2 cup of ice cubes
– Coarse salt
– Lime
– Cocktail Shaker (improvise if you do not have one) or blender for frozen margarita
– Margarita glass (any glass will do, but a margarita glass adds to the experience)
Details:
Cut lime into wedges, and then take one wedge and moisten the rim of the glass with the wedge. Pour coarse salt onto a plate and dip the moistened rim of the glass into the salt. Add a 1/2 cup of ice to the glass.
Add 1 cup of ice to shaker. Pour the tequila, triple sec, and lime juice into a shaker. Shake for 20-25 seconds, until the shaker is frosted on the outside. Strain the margarita into the glass and garnish with a slice of lime. If you prefer a frozen margarita, skip the shaker and instead add 2 cups of ice to a blender and then pour tequila, triple sec, and lime juice into the blender and blend until smooth. If you do not have a cocktail shaker, any closable liquid-tight container may do the trick...so long as you can shake vigorously without the beverage getting all over your code.
Enjoy the refreshing goodness of a classic margarita!
Time to Code - Jakarta EE Starter
Now that we have a cocktail, it is time to code! In this example, we are going to build a simple web service using Jakarta RESTful Web Services, and deploy to a Payara application server. While it is easy to deploy to a Docker or Podman container, in this example I will deploy to a standard application server.
Creating a Simple Web Service
To get started, head over to Eclipse Starter for Jakarta EE and choose your project options from the generator. In this example, please choose:
– Jakarta EE Version: Jakarta EE 10
– Jakarta EE Profile: Platform
– Java SE Version: Java SE 17
– Runtime: Payara
– Docker Support: Yes (this way you can experiment with Docker if you wish)
Once the options are selected, click the "Generate" button, and a ZIP file will be downloaded to your device. Once downloaded and unzipped to your machine, open the README file to learn how to start the project and run it. At a minimum, you need to do the following:
1) Ensure your JAVA_HOME environment variable is set to the appropriate JDK for the version you selected at the Jakarta EE Starter. In this case, ensure that your JAVA_HOME is pointing to JDK 17. On OS X, the following will set the home accordingly:
export JAVA_HOME=/Library/Java/JavaVirtualMachines/<java-home>>
2) Unzip the downloaded project. Traverse into the jakartaee-hello-world directory within a command prompt or terminal, and execute the following in order to invoke Maven to download dependencies and run the application/service:
./mvnw clean package cargo:run
3) Once the server has been started, navigate to the following page in a web browser: http//localhost:8080/jakartaee-hello-world/
This minimialistic application will simply output a Jakarta EE logo and some text onto the screen. To initiate the RESTful web service, visit the following URL:
http//localhost:8080/jakartaee-hello-world/rest/hello
This web service will return the JSON {"hello":"world"} and it does so by invoking a Jakarta REST web service and returning text to the caller. The RESTful service accepts a parameter identified as “name”, and if any word is passed to this parameter, then the JSON will be modified to {"hello”:<name>}. To invoke the web service passing the name “Jane”, open a web browser or use a curl command in a terminal open the following URL:
http://localhost:8080/jakartaee-hello-world/rest/hello?name=Jane
A REST web service endpoint class named HelloWorldResource is where the magic happens. Open the jakartaee-hello-world project within your favorite Integrated Development Environment (IDE) or use a text editor to open the org/eclipse/jakarta/HelloWorldResourc.java file. The HelloWorldResource class is annotated with @Path to indicate the URI path for invoking the REST web service. There is a single method named hello is contained within the class. The @GET annotation is placed on the method to indicate that the method is responding to HTTP GET requests, and the @Produces annotation ensures that the application will produce or return the JSON media type. The method accepts a QueryParam identified as name, which should be noted as the ?name portion from the above URL. In the body of the method, if the name parameter is null or empty, then the word “world” will be assigned to it. The method returns an object identified as Hello, which is a plain old Java object (POJO). If you wish to compile and deploy this application to a stand alone server, then you can do that as well! Here is a look at the HelloWorldResource REST service class:
public class HelloWorldResource {
@GET
@Produces({ MediaType.APPLICATION_JSON })
public Hello hello(@QueryParam("name") String name) {
if ((name == null) || name.trim().isEmpty()) {
name = "world";
}
return new Hello(name);
}
}
Code for the Hello object:
public class Hello {
private String name;
public Hello(String name) {
this.name = name;
}
public String getHello(){
return name;
}
}
There you have it! Now you should be able to get up and running quickly with the Jakarta EE Starter. Thanks to the team involved with working on the starter project!
