Getting Started

Creating a new Project

We use Maven Archetypes to generate a template for you to get started.

First, create a directory called GLProjects:

$ mkdir GLProjects
$ cd GLProjects

Next, run the following command to create a new starter project:

$ mvn archetype:generate -DarchetypeGroupId=com.ociweb -DarchetypeArtifactId=greenlighter -DarchetypeVersion=1.0.2

You will then be prompted to fill out some information:

Define value for property 'groupId': com.ociweb
Define value for property 'artifactId': Hello
Define value for property 'version' 1.0.0: : 
Define value for property 'package' com.ociweb: : 
Define value for property 'mainClass': RestServer

Hit "Y" to finish generating your new project.

This will generate a new GreenLightning project for us to start coding. Open up the project in your favorite IDE (such as IntelliJ IDEA or Eclipse) and navigate to the src/main/java/com.ociweb folder:

• GreenLightning.java - This file is responsible for spinning up a new GreenLightning runtime and can be ignored for the rest of this tutorial.

• RestServer.java - This is the main file we will work with. It will setup our HTTP server, connect behaviors and routes, and configure connection settings.

• HelloField.java - This will contain enums required for field identification.

• HelloStruct.java- This will contain enums for route identification.

Setting up a HTTP Server

GreenLighting allows you to use a lot of different servers - you're not just limited to HTTP. In this example, we will be using HTTP, so we need to specify and create our HTTP 1.x server.

Open up RestServer.java. It should look something like this:

RestServer.java

package com.ociweb;

import com.ociweb.gl.api.GreenFramework;
import com.ociweb.gl.api.GreenApp;
import com.ociweb.gl.api.GreenRuntime;

public class RestServer implements GreenApp {
    @Override
    public void declareConfiguration(GreenFramework builder) {
       //define your features here
    }
    @Override
    public void declareBehavior(GreenRuntime runtime) {
       //register your behaviors here       
    }
}

The declareConfiguration method is responsible for configuring your server. This includes HTTP settings such as protocol version, maximum connection, maximum response size, etc... It also provides a place to register your routes and define JSON.

The declareBehavior method is a place to register your behaviors and listeners. A listener is a behavior that can listen to any generic request (this could be a MQTT topic or a HTTP request). In our case, we will be registering REST listeners here.

Talking HTTP

First, let's focus on the declareConfiguration section and use the provided Builder object to specify HTTP and turn off TLS (only for this tutorial, by default it should always be enabled):

RestServer.java

@Override
public void declareConfiguration(GreenFramework builder) {
   //define your features here
    builder.useHTTP1xServer(8000)  // Specify the port the server will run on.
           .useInsecureServer();  // We disable TLS for this tutorial. 
}

That's how simply it is to tell GreenLightning to use a HTTP server. We specify port 8000 and turn off TLS.

Creating Routes

GET Request

Next, we need to tell GreenLightning about our routes and their containing fields. For the simply GET Hello World request, this is very simple. Add the following inside the declareConfiguration method:

RestServer.java

builder.defineRoute()
        .path("/api/hello/${NAME}")
        .refineString("NAME", HelloField.NAME, "DefaultName")
        .routeId(HelloStruct.HELLO_WORLD);

Don't panic! We will create the enums required on the next page.

Here, we use the defineRoute method on builder to start creating our route. On that object, we set our path with the ${NAME} placeholder, which we will use for creating our greeting message. We then need to associate the field key with the enum using the refineString method and set our route identifier and default value for name.

POST Request

Our POST request will look like this:

RestServer.java

....
builder.defineRoute()
        .parseJSON()
                .integerField("money", HelloField.MONEY)
                .integerField("age", HelloField.AGE)
                .stringField("name", HelloField.NAME)
        .path("/api/about")
        .routeId(HelloStruct.ABOUT);

Unlike the previous route, we first tell the builder that we are expecting JSON in our request body and that we would like to parse it. We then map the JSON keys to our enums (that we will create on the next page) and define the path.

On the next page, we will talk about Structures and Fields and how they tie in with route and request management.