[Detailed Tutorial] QBit microservice example

Note this is a good tutorial, but if you want more information and more examples see QBit Microservices Tutoiral Series and QBit Microservices Lib Examples.

Overview

QBit is a micro service framework. Let's create a simple QBit example. We will create a TODO example with QBit and gradle. Later examples will show how to do this with maven and QBit.

QBit is very fast. The programming model seems easy, there is some powerful things going on underneath the covers. QBit enables development of async services and in-memory services. We will cover more details in future tutorials. This tutorial is to break the ice.

The example we create will be available via REST/JSON. We will make it a standalone application using Gradle. The example will be CURLable. You can access it from the command line utility called curl.

CURLable example

To query the size of the todo list:

curl localhost:8080/services/todo-service/todo/count

To add a new TODO item.

curl -X POST -H "Content-Type: application/json" -d '{"name":"xyz","decription":"xyz"}' http://localhost:8080/services/todo-service/todo

To get a list of TODO items

curl http://localhost:8080/services/todo-service/todo/

Gradle build file

To run the sample app easily and to generate executable artifacts we will use gradle.

Here is the gradle build file.

group = 'io.advantageous.qbit.examples'

apply plugin: 'idea'
apply plugin: 'java'
apply plugin: 'maven'
apply plugin: 'application'

version = '0.1-SNAPSHOT'


sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8


sourceSets {
    main {
        java {
            srcDir 'src/main/java'
        }
        resources {
            srcDir 'src/main/resources'
        }
    }
}


mainClassName = "io.advantageous.qbit.vertx.http.PerfClientTest"

repositories {
    mavenLocal()
    mavenCentral()
}



dependencies {
    compile group: 'io.advantageous.qbit', name: 'qbit-vertx', version: '0.6.1'
    compile "org.slf4j:slf4j-api:[1.7,1.8)"
    compile 'ch.qos.logback:logback-classic:1.1.2'
    testCompile group: 'junit', name: 'junit', version: '4.10'
}




idea {
    project {
        jdkName = '1.8'
        languageLevel = '1.8'
    }
}

There are plugins for IntelliJ and for Eclipse for gradle. You will need to install gradle. Go here for instructions for installing gradle.

Java POJO for TODO

QBit is simple, and easy to use framework for building REST services. You might be surprised just how easy. QBit can turn most Java POJOs into JSON with no annotations.

The gradle file will be more complicated than our Java code. :)

Here is the the TODO item for our example:

package io.advantageous.qbit.examples;

import java.util.Date;


public class TodoItem {


    private final String description;
    private final String name;
    private final Date due;

    public TodoItem(final String description, final String name, final Date due) {
        this.description = description;
        this.name = name;
        this.due = due;
    }

    public String getDescription() {
        return description;
    }

    public String getName() {
        return name;
    }

    public Date getDue() {
        return due;
    }
}

Java Service for TODO

The TODO service is defined as follows:

package io.advantageous.qbit.examples;


import io.advantageous.qbit.annotation.RequestMapping;
import io.advantageous.qbit.annotation.RequestMethod;

import java.util.ArrayList;
import java.util.List;


@RequestMapping("/todo-service")
public class TodoService {


    private List<TodoItem> todoItemList = new ArrayList<>();


    @RequestMapping("/todo/count")
    public int size() {

        return todoItemList.size();
    }

    @RequestMapping("/todo/")
    public List<TodoItem> list() {

        return todoItemList;
    }

    @RequestMapping(value = "/todo", method = RequestMethod.POST)
    public void add(TodoItem item) {

        todoItemList.add(item);
    }

}

Main method to run service

Notice the use of RequestMapping, it works in much the same way as the Spring MVC REST annotations. It provides a subset of what Spring MVC provides.

The add method gets called when someone POSTs to the URI /todo.

To run this service, you need to start it up. You do this with a ServiceEndpointServer. Starting up a ServiceEndpointServer is easier than you might think. A service bundle can specify different threading models so that all services in the bundle run in the same thread or run in different threads.

QBit uses apartment model threading for Services. It uses a very efficient queuing mechanism to limit the amount of handoff between the IO threads and the service threads.

Main method

package io.advantageous.qbit.examples;

import io.advantageous.qbit.server.ServiceEndpointServer;
import io.advantageous.qbit.server.EndpointServerBuilder;

public class TodoMain {

    public static void main(String... args) {
        ServiceEndpointServer server = new EndpointServerBuilder().build();
        server.initServices(new TodoService());
        server.start();
    }

}

EndpointServerBuilder allows you to setup properties like PORT and NIC interface that you are binding your service to. It also has tweak-able settings for performance, which will make more sense to cover in and advanced tutorial.

Services are available over REST and WebSocket.

To run this service, you need gradle.

Gradle commands you might care about:

gradle idea

The above generates an idea project. There is also a gradle plugin for Eclipse.

gradle run

The above runs the example from gradle.

gradle distZip
unzip ./build/distributions/qbit-example-0.1-SNAPSHOT.zip
qbit-example-0.1-SNAPSHOT/bin/qt-example

Since we are using gradle we can easily distribute a zip file (or tar file) with all of the jar files we need to execute our service.

This concludes our first getting started tutorial. QBit is very fast. But although the programming model seems easy, there is some powerful things going on underneath the covers. QBit enables development of async services and in-memory services. We will cover more in future tutorials. Stay tuned.

If you are in a hurry and want more information, see More examples of using QBit.

Note this is a good tutorial, but if you want more information and more examples see QBit Microservices Tutoiral Series and QBit Microservices Lib Examples.