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 the name J4C (Java for Cloud).
In this tutorial, we’ll cover the main concepts of the framework and then we’ll 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 Java 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 in more details 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>0.10.4</version>
</dependency>
To have a simple web application, we can use one of the following builder methods: WebServer.create(serverConfig, routing) 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 greeting message for any HTTP request with ‘/greet’ path and GET Method:
public static void main(String... args) throws Exception {
ServerConfiguration serverConfig = ServerConfiguration.builder()
.port(9001).build();
Routing routing = Routing.builder()
.get("/greet", (request, response) -> response.send("Hello World !")).build();
WebServer.create(serverConfig, routing)
.start()
.thenAccept(ws ->
System.out.println("Server started at: http://localhost:" + ws.port())
);
}
The last line is to start the server and wait for serving 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 Actually 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.4</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 both the port and the path using the builder pattern.
Helidon SE also allows using a config pattern where the configuration data is provided by the Config API. This 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>0.10.4</version>
</dependency>
To read the configuration data, we just 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();
int pageSize = config.get("web.page-size").asInt();
boolean debug = config.get("web.debug").asBoolean();
String userHome = config.get("user.home").asString();
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>0.10.4</version>
</dependency>
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 behavior by disabling 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 sources configurations, that is, 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 need, Helidon allows us to provide an implementation for our configuration source. For example, we can provide an implementation that can 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 just 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 for 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.10.4</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’re going to 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>0.10.4</version>
</dependency>
<dependency>
<groupId>io.helidon.security</groupId>
<artifactId>helidon-security-provider-http-auth</artifactId>
<version>0.10.4</version>
</dependency>
<dependency>
<groupId>io.helidon.security</groupId>
<artifactId>helidon-security-integration-webserver</artifactId>
<version>0.10.4</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 = //...
UserStore 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 configuration 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 just 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.from(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.from(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.from(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.
As 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-1.2</artifactId>
<version>0.10.4</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-json-binding</artifactId>
<version>2.26</version>
</dependency>
The helidon-microprofile-1.2 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 and 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 over on GitHub.