HTTP Client

Your GreenLightning app can also function as a HTTP client for sending REST requests, etc... to other servers and parsing the response.

Please refer to the GreenLightning-API repo for more examples like this one.

Use the code below to get started with creating a HTTP client.

Example

This is an example GreenLightning App in which we want to hit up a server somewhere containing JSON weather data (or see Simple REST Server on how to build your own REST service).

In this example, we build a simple app that performs a GET request to a local server which servers a static JSON file containing "wather data":

First, we create our client. We specify that we are also acting as a HTTP client on line 8, and create the client instance on line 11. We also declare the JSON fields we care about.

Client.java

public class Client implements GreenApp
{
    private ClientHostPortInstance weatherSession;

    @Override
    public void declareConfiguration(Builder config) {
        // In this example, we have TLS enabled.
        HTTPClientConfig netClientConfig = config.useNetClient();

        // We directly parse JSON of the current session.
        weatherSession = netClientConfig.createHTTP1xClient("127.0.0.1", 443)
                .parseJSON()
                    .stringField("condition", WeatherFields.WEATHER_CONDITIONS)
                    .decimalField("temperature", WeatherFields.TEMP_KELVIN)
                .finish();
    }

    @Override
    public void declareBehavior(GreenRuntime runtime) {
        // Add the weather behavior here.
        runtime.addResponseListener(new WeatherBehavior(runtime, weatherSession))
                .acceptHostResponses(weatherSession);
    }
    
}

Create the field identifiers:

WeatherFields.java

package com.ociweb;

public enum WeatherFields {
    WEATHER_CONDITIONS, TEMP_KELVIN
}

WeatherBehavior will be responsible for sending out the request and receiving the response. We use a HTTPRequestService to do this.

WeatherBehavior.java

public class WeatherBehavior implements HTTPResponseListener, StartupListener, ShutdownListener {
    // Keep track of active session for get request.
    private ClientHostPortInstance session;
    
    // This will actually perform the request.
    private final HTTPRequestService clientService;

    public WeatherBehavior(GreenRuntime runtime, ClientHostPortInstance session) {
        // Create the request service.
        clientService = runtime.newCommandChannel().newHTTPClientService();
        this.session = session;
    }

    @Override
    public void startup() {
        // Send out the request on startup.
        clientService.httpGet(session, "/api/weather");
    }
    
    @Override
    public boolean acceptShutdown() {
        // Close the session when shutting down.
        return clientService.httpClose(session);
    }

    @Override
    public boolean responseHTTP(HTTPResponseReader reader) {
        // We need to open the payload data.
        reader.openPayloadData( (r)-> {
            // Since we want to directly parse the fields, it needs to be structured.
            StructuredReader s = r.structured();

            // Read the fields from JSON.
            double tempKelvin = s.readDecimalAsDouble(WeatherFields.TEMP_KELVIN);
            String conditions = s.readText(WeatherFields.WEATHER_CONDITIONS);

            // Do whatever you'd like with the data here, this is just a short example.
            // Usually, you would use a PubSub service to send this information back to
            // another behavior.
            System.out.println(conditions + ", " + tempKelvin);
        });

        return true;
    }
}

Methods

HTTPRequestService.httpGet(ClientHostPortInstance session, String route, optional: HeaderWritable headers)

Sends a GET request to the route (host is defined in session). Optional headers can be written.

clientService.httpGet(session, "/api/weather");

clientService.httpGet(session, "/shopping", 
                header -> header.write(HTTPHeaderDefaults.SET_COOKIE, "__Secure-ID=123; Secure; Domain=example.com"));

You can also write multiple headers:

clientService.httpGet(session, "/shopping",
        header -> {
            header.write(HTTPHeaderDefaults.SET_COOKIE, "__Secure-ID=123; Secure; Domain=example.com");
            header.write(HTTPHeaderDefaults.DATE, "Wed, 21 Oct 2018 07:28:00 GMT");
});

HTTPRequestService.httpPost(ClientHostPortInstance session, String route, Writable payload)

Sends a POST request to the route (host is defined in session). Optional headers can be written.

clientService.httpPost(session, "/post_comment", payload -> {
            payload.writeUTF("This is a comment.");
});

HTTPRequestService.httpPost(ClientHostPortInstance session, String route, HeaderWritable headers, Writable payload)

Sends a POST request to the route (host is defined in session) with custom headers.

clientService.httpPost(session, "/post_comment",
                header-> header.write(HTTPHeaderDefaults.DATE, "Wed, 21 Oct 2018 07:28:00 GMT"),
                payload -> {
                    payload.writeUTF("This is a comment.");
                });

HTTPRequestService.httpClose(ClientHostPortInstance session)

Closes the current session. Usually, you want to call this in the acceptShutdown() method using a ShutdownListener in your behavior.

@Override
public boolean acceptShutdown() {
    return clientService.httpClose(session);
}