

Adding Extensions¶

Startup extension¶

In WSO2 API Microgateway, a startup extension can be used to implement any requirement during the server starts up. By writing customized code inside the startup extension you can do anything when the server starts up.

For example, you can load whatever you want into memory by defining your own object model in your customized code. The startup_extension.bal file, which is inside the <PROJECT_HOME>/extensions directory, can be extended using the custom code. The following sub-sections explain how you can work with the start-up extensions to define your own model.

The following is an example of a startup extension that you can use to make a call to the public Petstore API pet/{petid} resource and store the response against the ID in a global map when the server starts up.

Write the customized Java startup extension. For example let's write an extension to store the response from Petstore API against the PetId.

Write the extension to store the response from Petstore API

package org.wso2.apimgt.gateway.cli.startup;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.wso2.apimgt.gateway.cli.constants.RESTServiceConstants;
import org.wso2.apimgt.gateway.cli.utils.RESTAPIUtils;

import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;

/**
*  This class is to load the response into memory by calling the public Petstore API against id.
*/
 class StoreResponse {
    private static final Logger log = LoggerFactory.getLogger("ballerina");
    private static Map<Integer, String> responseHashMap = new HashMap<>();

    public static void readDataToMemory() {
        URL url;
        HttpURLConnection urlConn = null;
        try {
            for (int i = 2; i < 3; i++) {
                String urlStr = "https://petstore.swagger.io/v2/pet/" + i;
                url = new URL(urlStr);
                urlConn = (HttpURLConnection) url.openConnection();
                urlConn.setDoOutput(true);
                urlConn.setRequestMethod(RESTServiceConstants.GET);
                int responseCode = urlConn.getResponseCode();
                log.debug("Response code: {}", responseCode);
                if (responseCode == 200) {
                    String responseStr = RESTAPIUtils.getResponseString(urlConn.getInputStream());
                    responseHashMap.put(i,responseStr);
                    log.trace("Response body: {}", responseStr);
                } else {
                    throw new Exception("Error occurred " + responseCode);
                }
             }
        } catch (IOException e) {

        // handle exception
         } catch (Exception e) {
            e.printStackTrace();
         } finally {
             if (urlConn != null) {
                urlConn.disconnect();
             }
         }
     }
 }

Define the class of the the customized extension as a startup extension. By default, the startup_extension.bal file is an empty function. You can modify this class to achieve the custom logic by writing a Java startup extension.

Write the customized startup extension in startup_extension.bal file

import ballerinax/java;

# Represents the startup extension filter.
#
#
public function startupExtension() {
    loadDataToMemory();
}

# This function is used to load response from petstore API by id into memory during the server starts up.
#
function loadDataToMemory() = @java:Method {
name: "readDataToMemory",
class: "org.wso2.apimgt.gateway.cli.startup.StoreResponse"
} external;

Add the startup extension to the project.
Build the startup extension project. After the building process is complete, you will derive a JAR as an output.
Place the latter mentioned JAR in the <MGW-project>/lib directory.

Note

If your startup extension consists of any third-party libraries, you should also place these custom JARs in the MGW-project>/lib directory.

Extension filter¶

In WSO2 API Microgateway, the users can customize and extend the request and response handling process using the extension filter object. The extension filter object is defined in the extension_filter.bal file, which is located in the <MGW-HOME>/extension directory.

Info

It is written in Ballerina 1.2.x so follow API docs in Ballerina documentation for language guide.

The following is an example of an extension filter to customize the throttled out responses (e.g. error code, error message, and error description).

Writing a customized extension filter

import ballerina/http;
import wso2/gateway;


# Represents the extension filter, which used to customize and extend the request and response handling
#
#
public type ExtensionFilter object {
    # Request filter function.
    # + caller - http caller object.
    # + request - http request object.
    # + context - http filter context object.
    # + return - Whether the filter has passed or not
    public function filterRequest (http:Caller caller, http:Request request, http:FilterContext context) returns
    boolean {
        return true;
    }

    public function filterResponse(http:Response response, http:FilterContext context) returns boolean {
        var failed =  context.attributes[gateway:FILTER_FAILED];
        if (failed is boolean) {
            if (failed) {
                    int statusCode = <int>context.attributes[gateway:HTTP_STATUS_CODE];
                    if(statusCode == gateway:THROTTLED_OUT) {
                        setThrottleFailureResponse(response, context );
                     } 
                     return true;
                     //return gateway:createFilterResult(false, statusCode, errorMessage);
            }
        } else {
        //Nothing to handle
            return true;
        }
        return true;
    }

};

# This method can be used to send custom error message when message throttled out
#
function setThrottleFailureResponse(http:Response response, http:FilterContext context) {
    int statusCode = <int>context.attributes[gateway:HTTP_STATUS_CODE];
    string errorDescription = <string>context.attributes[gateway:ERROR_DESCRIPTION];
    string errorMesssage = <string>context.attributes[gateway:ERROR_MESSAGE];
    int errorCode = <int>context.attributes[gateway:ERROR_CODE];
    response.statusCode = statusCode;
    response.setContentType(gateway:APPLICATION_JSON);
    json payload = {fault : {
      code : errorCode,
      message : errorMesssage,
      description : errorDescription
    }};
    response.setJsonPayload(payload);
}

Top