WSO2 Microservices Framework for Java (MSF4J)

WSO2 Microservices Framework for Java (MSF4J) is a lightweight high performance framework for developing & running microservices.

WSO2 MSF4J is one of the highest performing lightweight Java microservices frameworks. The following graphs show the throughput, memory consumption & latency characteristics of MSF4J against other microservices frameworks.

EchoThroughput

An echo service which accepts a 1KB request & echoes it back directly and using a temp file was developed for the respective frameworks, and requests were sent for different concurrency values. The test was repeated for each concurrency value for each framework and the average throughput was calculated. Tests were run out of the box without any tuning on 32 core 64GB server in JVM v1.8.0_60 with default configuration.

EchoMemory

Memory usage for each framework was observed after running the 1KB payload echo microservice on each framework & sending a number of requests at different concurrency levels to each service. The graph above shows the averaged out values after several runs for each framework.

Latency results was observed using the Apache bench provided percentile values. Results were plotted for various concurrency levels the simple echo test.

MeanLatency

Tests were run out of the box without any tuning on 32 core 64GB server in JVM v1.8.0_60 with default configuration.

More details about the performance test can found here.

Hello world with MSF4J

It is really easy to define & deploy a Java microservice using WSO2 MSF4J. You simply need to annotate your service and deploy it using a single line of code.

Let's get started by writing a hello world MSF4J microservice.

You can use the msf4j-microservice Maven archetype to create your first MSF4J project. Make sure you have JDK 1.8 and Maven 3.x installed, & run the following command.

mvn archetype:generate -DarchetypeGroupId=org.wso2.msf4j \
-DarchetypeArtifactId=msf4j-microservice -DarchetypeVersion=2.6.2 \
-DgroupId=org.example -DartifactId=Hello-Service -Dversion=0.1-SNAPSHOT \
-Dpackage=org.example.service -DserviceClass=HelloService

This will generate a project structure for you to quickly get started. Next navigate to the Hello-Service directory. You will find a pom.xml file and also an src directory.

pom.xml

This pom file inherits from the msf4j-service/pom.xml. It provides a way of setting things up quickly with minimum amount of configuration. Click here for more information.

<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">

    <parent>
        <groupId>org.wso2.msf4j</groupId>
        <artifactId>msf4j-service</artifactId>
        <version>2.6.2</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>Hello-Service</artifactId>
    <version>0.1-SNAPSHOT</version>
    <name>WSO2 MSF4J Microservice</name>

    <properties>
        <microservice.mainClass>org.example.service.Application</microservice.mainClass>
    </properties>

</project>

You don't need to change anything in this pom.xml file.

HelloService.java

Change the org.example.service.HelloService class as follows to echo back the name input parameter. You can remove the auto generated code and replace it with the following code segment:

package org.example.service; 

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

@Path("/hello")
public class HelloService {

    @GET
    @Path("/{name}")
    public String hello(@PathParam("name") String name) {
        return "Hello " + name;
    }

}

Application.java

This is the one-liner to deploy your service using WSO2 MSF4J.

public class Application {
    public static void main(String[] args) {
        new MicroservicesRunner()
                .deploy(new HelloService())
                .start();
    }
}

You can also pass in the port(s) as an argument to the MicroservicesRunner class constructor. When passing the port(s) as an argument, by default it binds to 0.0.0.0 host. Use "msf4j.host" environment variable to override the host value.

Build the Service

Run the following Maven command. This will create the fat jar Hello-Service-0.1-SNAPSHOT.jar in the target directory.

mvn package

This fat jar is a jar file that contains your microservice as well as all its dependencies.

Run the Service

You just have to run the following command to get your service up and running.

java -jar target/Hello-Service-*.jar

Test the Service with cURL

Run the following command or simply go to [http://localhost:8080/hello/wso2] (http://localhost:8080/hello/wso2) from your browser.

curl http://localhost:8080/hello/wso2

You should see a response that prints "Hello wso2"

Supported Annotations

In this section, we will look at the annotations used in MSF4J microservices. As you may have already noticed, we support a subset of the JAXRS annotations.

Class level annotations

@Path

Root path for resource methods. All the paths specified in the resource methods will be sub paths of this.

@Consumes

Default consume media type(s) for resource methods. The resource methods that do not specify @Consume annotation will inherit this consume media type(s).

@Produces

Default produce media type(s) for resource methods. The resource methods that do not specify @Produce annotation will inherit this produce media type(s).

Method level annotations

@Path

Endpoint of the resource method relative to @Path of the container resource class.

@Consumes

Media type(s) that the method can consume. This overrides the class level @Consumes media types.

@Produces

Media type(s) that is produced by the method. This overrides the class level @Produces media types.

@GET

HTTP GET method. Specify that the resource method supports HTTP GET method.

@PUT

HTTP PUT method. Specify that the resource method supports HTTP PUT method.

@POST

HTTP POST method. Specify that the resource method supports HTTP POST method.

@DELETE

HTTP DELETE method. Specify that the resource method supports HTTP DELETE method.

@HEAD

HTTP HEAD method. Specify that the resource method supports HTTP HEAD method.

@OPTIONS

HTTP OPTIONS method. Specify that the resource method supports HTTP OPTIONS method.

Parameter level annotations

@DefaultValue

Specify a default value for a resource method parameter. The value will be automatically converted to the corresponding parameter's type.

@Context

Inject additional objects to a resource method. Currently supports injection of the following objects.

org.wso2.msf4j.Request - This object can be used to access properties of the HTTP request. The transport session (org.wso2.msf4j.Session) can also be accessed via org.wso2.msf4j.Request#getSession(). See the Session-aware service sample.
org.wso2.msf4j.Response - This object can be used to send HTTP responses. You can make responses more clean way by returning an instance of javax.ws.rs.core.Response or a POJO. See the [StockQuote-Service] (samples/stockquote/fatjar) sample.
org.wso2.msf4j.HttpStreamer - This object can be used to stream a chunked request body and process it while the request is streaming. See the FileServer sample.
org.wso2.msf4j.formparam.FormParamIterator - This object can be used to stream a HTML form submission request body and process it while the request is streaming. See the FormParam sample.

@PathParam

/StockQuote/{symbol} to get value of symbol. The value will be automatically converted to the corresponding parameter type and assigned to that parameter.

@QueryParam

/Students?age=18 to get value of age. The value will be automatically converted to the corresponding parameter type and assigned to that parameter.

@HeaderParam

To read HTTP request header values. The value will be automatically converted to the corresponding parameter type and assigned to that parameter.

@CookieParam

Extracts the value from the specified cookie, converts to the corresponding parameter type and assigns the value to that parameter.

@FormParam

To support HTML form submission with application/x-www-form-urlencoded and multipart/form-data The value will be automatically converted to the corresponding parameter type and assigned to that parameter

@FormDataParam

To support complex form submission with multipart/form-data content type. E.g file uploads and beans. The values will be automatically converted to the corresponding parameter type and assigned to that parameter

Lifecycle Callback Methods

Support following Java lifecycle callback method annotations.

@PostConstruct

Invoke by the container on newly constructed service instances after all dependency injection has completed and before transport starts.

@PreDestroy

Invoke by the container during server shutdown before the container removes the service instance.

For a detailed example, check out the lifecycle sample here.

MSF4J Interceptors

Please do refer the following for complete instructions.

[General instructions](/sam

Msf4j

Install / Use

README

WSO2 Microservices Framework for Java (MSF4J)

Hello world with MSF4J

pom.xml

HelloService.java

Application.java

Build the Service

Run the Service

Test the Service with cURL

Supported Annotations

Class level annotations

@Path

@Consumes

@Produces

Method level annotations

@Path

@Consumes

@Produces

@GET

@PUT

@POST

@DELETE

@HEAD

@OPTIONS

Parameter level annotations

@DefaultValue

@Context

@PathParam

@QueryParam

@HeaderParam

@CookieParam

@FormParam

@FormDataParam

Lifecycle Callback Methods

@PostConstruct

@PreDestroy

MSF4J Interceptors