1. Overview
Helidon is the new Java microservice framework that has been open-sourced recently by Oracle. It was used internally in Oracle projects under J4C (Java for Cloud).
In this tutorial, we’ll cover the framework’s main concepts and then move to build and run a Helidon based microservice.
2. Programming Model
Currently, the framework supports two programming models for writing microservices: Helidon SE and Helidon MP.
While Helidon SE is designed to be a microframework that supports the reactive programming model, Helidon MP, on the other hand, is an Eclipse MicroProfile runtime that allows the Jakarta EE community to run microservices in a portable way.
In both cases, a Helidon microservice is a Java SE application that starts a tinny HTTP server from the main method.
3. Helidon SE
In this section, we’ll discover the main components of Helidon SE: WebServer, Config, and Security.
3.1. Setting up the WebServer
To get started with the WebServer API, we need to add the required Maven dependency to the pom.xml file:
<dependency>
<groupId>io.helidon.webserver</groupId>
<artifactId>helidon-webserver</artifactId>
<version>3.2.2</version>
</dependency>
To have a simple web application, we can use one of the following builder methods: WebServer.create(routing, serverConfig) or just WebServer.create(routing). The last one takes a default server configuration allowing the server to run on a random port.
Here’s a simple Web application that runs on a predefined port. We’ve also registered a simple handler that will respond with a greeting message for any HTTP request with a ‘/greet’ path and GET Method:
public static void main(String... args) throws Exception {
Routing routing = Routing.builder()
.get("/greet", (request, response) -> response.send("Hello World !")).build();
WebServer.builder(routing)
.port(9001).addRouting(routing).build()
.start()
.thenAccept(ws ->
System.out.println("Server started at: http://localhost:" + ws.port())
);
}
The last line is to start the server and wait to serve HTTP requests. But if we run this sample code in the main method, we’ll get the error:
Exception in thread "main" java.lang.IllegalStateException:
No implementation found for SPI: io.helidon.webserver.spi.WebServerFactory
The WebServer is an SPI, and we need to provide a runtime implementation. Currently, Helidon provides the NettyWebServer implementation, which is based on Netty Core.
Here’s the Maven dependency for this implementation:
<dependency>
<groupId>io.helidon.webserver</groupId>
<artifactId>helidon-webserver-netty</artifactId>
<version>0.10.6</version>
<scope>runtime</scope>
</dependency>
Now, we can run the main application and check that it works by invoking the configured endpoint:
http://localhost:9001/greet
In this example, we configured the port and the path using the builder pattern.
Helidon SE also allows using a config pattern where the Config API provides the configuration data. This is the subject of the next section.
3.2. The Config API
The Config API provides tools for reading configuration data from a configuration source.
Helidon SE provides implementations for many configuration sources. The default implementation is provided by helidon-config, where the configuration source is an application.properties file located under the classpath:
<dependency>
<groupId>io.helidon.config</groupId>
<artifactId>helidon-config</artifactId>
<version>3.2.2</version>
</dependency>
To read the configuration data, we need to use the default builder, which by default takes the configuration data from application.properties:
Config config = Config.builder().build();
Let’s create an application.properties file under the src/main/resource directory with the following content:
server.port=9080
web.debug=true
web.page-size=15
user.home=C:/Users/app
To read the values, we can use the Config.get() method followed by a convenient casting to the corresponding Java types:
int port = config.get("server.port").asInt().get();
int pageSize = config.get("web.page-size").asInt().get();
boolean debug = config.get("web.debug").asBoolean().get();
String userHome = config.get("user.home").asString().ge();
In fact, the default builder loads the first found file in this priority order: application.yaml, application.conf, application.json, and application.properties. The last three format needs an extra related config dependency. For example, to use the YAML format, we need to add the related YAML config dependency:
<dependency>
<groupId>io.helidon.config</groupId>
<artifactId>helidon-config-yaml</artifactId>
<version>3.2.2</version>
</dependency>
NOTE: If we add the helidon-config-yaml dependency, it will fetch by default as a transient dependency the helidon-config packages.
And then, we add an application.yml:
server:
port: 9080
web:
debug: true
page-size: 15
user:
home: C:/Users/app
Similarly, to use the CONF, which is a JSON simplified format, or JSON formats, we need to add the helidon-config-hocon dependency.
Note that the configuration data in these files can be overridden by environment variables and Java System properties.
We can also control the default builder behaviour by disabling the Environment variable and System properties or by specifying explicitly the configuration source:
ConfigSource configSource = ConfigSources.classpath("application.yaml").build();
Config config = Config.builder()
.disableSystemPropertiesSource()
.disableEnvironmentVariablesSource()
.sources(configSource)
.build();
In addition to reading configuration data from the classpath, we can also use two external source configurations: the git and the etcd configs. For this, we need the helidon-config-git and helidon-git-etcd dependencies.
Finally, if all of these configuration sources don’t satisfy our needs, Helidon allows us to provide an implementation for our configuration source. For example, we can provide an implementation to read the configuration data from a database.
3.3. The Routing API
The Routing API provides the mechanism by which we bind HTTP requests to Java methods. We can accomplish this by using the request method and path as matching criteria or the RequestPredicate object for using more criteria.
So, to configure a route, we can use the HTTP method as criteria:
Routing routing = Routing.builder()
.get((request, response) -> {} );
Or we can combine the HTTP method with the request path:
Routing routing = Routing.builder()
.get("/path", (request, response) -> {} );
We can also use the RequestPredicate for more control. For example, we can check for an existing header or the content type:
Routing routing = Routing.builder()
.post("/save",
RequestPredicate.whenRequest()
.containsHeader("header1")
.containsCookie("cookie1")
.accepts(MediaType.APPLICATION_JSON)
.containsQueryParameter("param1")
.hasContentType("application/json")
.thenApply((request, response) -> { })
.otherwise((request, response) -> { }))
.build();
Until now, we have provided handlers in the functional style. We can also use the Service class, which allows writing handlers in a more sophisticated manner.
So, let’s first create a model for the object we’re working with, the Book class:
public class Book {
private String id;
private String name;
private String author;
private Integer pages;
// ...
}
We can create REST Services for the Book class by implementing the Service.update() method. This allows configuring the subpaths of the same resource:
public class BookResource implements Service {
private BookManager bookManager = new BookManager();
@Override
public void update(Routing.Rules rules) {
rules
.get("/", this::books)
.get("/{id}", this::bookById);
}
private void bookById(ServerRequest serverRequest, ServerResponse serverResponse) {
String id = serverRequest.path().param("id");
Book book = bookManager.get(id);
JsonObject jsonObject = from(book);
serverResponse.send(jsonObject);
}
private void books(ServerRequest serverRequest, ServerResponse serverResponse) {
List<Book> books = bookManager.getAll();
JsonArray jsonArray = from(books);
serverResponse.send(jsonArray);
}
//...
}
We’ve also configured the Media Type as JSON, so we need the helidon-webserver-json dependency for this purpose:
<dependency>
<groupId>io.helidon.webserver</groupId>
<artifactId>helidon-webserver-json</artifactId>
<version>0.11.0</version>
</dependency>
Finally, we use the register() method of the Routing builder to bind the root path to the resource. In this case, Paths configured by the service are prefixed by the root path:
Routing routing = Routing.builder()
.register(JsonSupport.get())
.register("/books", new BookResource())
.build();
We can now start the server and check the endpoints:
http://localhost:9080/books
http://localhost:9080/books/0001-201810
3.4. Security
In this section, we will secure our resources using the Security module.
Let’s start by declaring all the necessary dependencies:
<dependency>
<groupId>io.helidon.security</groupId>
<artifactId>helidon-security</artifactId>
<version>3.2.2</version>
</dependency>
<dependency>
<groupId>io.helidon.security.providers</groupId>
<artifactId>helidon-security-providers-http-auth</artifactId>
<version>3.2.2</version>
</dependency>
<dependency>
<groupId>io.helidon.security.integration</groupId>
<artifactId>helidon-security-integration-webserver</artifactId>
<version>3.2.2</version>
</dependency>
The helidon-security, helidon-security-provider-http-auth, and helidon-security-integration-webserver dependencies are available from Maven Central.
The security module offers many providers for authentication and authorization. For this example, we’ll use the HTTP basic authentication provider as it’s fairly simple, but the process for other providers is almost the same.
The first thing to do is create a Security instance. We can do it either programmatically for simplicity:
Map<String, MyUser> users = //...
SecureUserStore store = user -> Optional.ofNullable(users.get(user));
HttpBasicAuthProvider httpBasicAuthProvider = HttpBasicAuthProvider.builder()
.realm("myRealm")
.subjectType(SubjectType.USER)
.userStore(store)
.build();
Security security = Security.builder()
.addAuthenticationProvider(httpBasicAuthProvider)
.build();
Or we can use a configuration approach.
In this case, we’ll declare all the security configurations in the application.yml file, which we load through the Config API:
#Config 4 Security ==> Mapped to Security Object
security:
providers:
- http-basic-auth:
realm: "helidon"
principal-type: USER # Can be USER or SERVICE, default is USER
users:
- login: "user"
password: "user"
roles: ["ROLE_USER"]
- login: "admin"
password: "admin"
roles: ["ROLE_USER", "ROLE_ADMIN"]
#Config 4 Security Web Server Integration ==> Mapped to WebSecurity Object
web-server:
securityDefaults:
authenticate: true
paths:
- path: "/user"
methods: ["get"]
roles-allowed: ["ROLE_USER", "ROLE_ADMIN"]
- path: "/admin"
methods: ["get"]
roles-allowed: ["ROLE_ADMIN"]
And to load it, we need to create a Config object, and then we invoke the Security.fromConfig() method:
Config config = Config.create();
Security security = Security.fromConfig(config);
Once we have the Security instance, we first need to register it with the WebServer using the WebSecurity.from() method:
Routing routing = Routing.builder()
.register(WebSecurity.create(security).securityDefaults(WebSecurity.authenticate()))
.build();
We can also create a WebSecurity instance directly using the config approach by which we load both the security and the web server configuration:
Routing routing = Routing.builder()
.register(WebSecurity.create(config))
.build();
We can now add some handlers for the /user and /admin paths, start the server and try to access them:
Routing routing = Routing.builder()
.register(WebSecurity.create(config))
.get("/user", (request, response) -> response.send("Hello, I'm Helidon SE"))
.get("/admin", (request, response) -> response.send("Hello, I'm Helidon SE"))
.build();
4. Helidon MP
Helidon MP is an implementation of Eclipse MicroProfile and also provides a runtime for running MicroProfile based microservices.
We already have an article about Eclipse MicroProfile; we’ll check out that source code and modify it to run on Helidon MP.
After checking out the code, we’ll remove all dependencies and plugins and add the Helidon MP dependencies to the POM file:
<dependency>
<groupId>io.helidon.microprofile.bundles</groupId>
<artifactId>helidon-microprofile</artifactId>
<version>3.2.2</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-json-binding</artifactId>
<version>3.1.2</version>
</dependency>
The helidon-microprofile and jersey-media-json-binding dependencies are available from Maven Central.
Next, we’ll add the beans.xml file under the src/main/resource/META-INF directory with this content:
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/beans_2_0.xsd"
version="2.0" bean-discovery-mode="annotated">
</beans>
In the LibraryApplication class, override getClasses() method so that the server won’t scan for resources:
@Override
public Set<Class<?>> getClasses() {
return CollectionsHelper.setOf(BookEndpoint.class);
}
Finally, create a main method and add this code snippet:
public static void main(String... args) {
Server server = Server.builder()
.addApplication(LibraryApplication.class)
.port(9080)
.build();
server.start();
}
And that’s it. We’ll now be able to invoke all the book resources.
5. Conclusion
In this article, we’ve explored the main components of Helidon, also showing how to set up either Helidon SE or MP. As Helidon MP is just an Eclipse MicroProfile runtime, we can run any existing MicroProfile based microservice using it.
As always, the code of all examples above can be found on GitHub.