DBAPI

# Plugin Development

# What is plugin

  • DBAPI provided 4 kinds of plugins, transform plugin/cache plugin/alarm plugin/global transform plugin

# Cache plugin

It is mainly for select sql API, sql query results can be cached, to avoid frequent query to the database

  • Cache logic is written by the user himself. Users can cache data to redis / mongodb / elasticsearch, etc.
  • If the cache is enabled, when the data cannot be query from the cache, DBAPI will query data from database and then set result to cache for next usage.

# Alarm plugin

  • When the API internal error occurs, the alarm plugin can alert the error information, such as sending email, sending message, etc.
  • The alarm logic is written by the user himself.

DBAPI has provided email alarm plugin, please modify sender properties in conf/plugin.properties file

# email alarm plugin global params
EMAIL_USERNAME=dbapi_test@163.com
EMAIL_PASSWORD=WGJQBFRIPUENHMUP
EMAIL_HOST=smtp.163.com

# Transform plugin

  • Sometimes sql cannot get the data with the format you want at once，it is more convenient to process the data with code，this is the time to use the transformation plugin.The user writes their own code for the data conversion logic.
  • Typical scenarios, such as encrypting the user's mobile phone number and bank card number in the sql query results

If there are multiple sql within an API, then each sql corresponds to a transformation plugin. The transformation plugin always works for a single sql query result

# Global transform plugin

  • The default data format returned by the API is{success:true,msg:xxx,data:xxx}
  • In some cases, the response data format needs to be transformed. For example, the front-end low-code framework AMIS requires that the data response from API must carry the status field. At this time, the global transform plugin can be used to convert the return data of the API

Note the difference between the transform plugin and the global transform plug-in. The transform plugin is used to transform the result from executor , while the global transform plugin is used to transform the entire API execution results

# How to develop plugin

# Preparation

  • Plugins developed by java, please install jdk(8+) , new maven project, introduce dbapi-plugin dependeny in pom.xml

<dependency>
    <groupId>com.gitee.freakchicken.dbapi</groupId>
    <artifactId>dbapi-plugin</artifactId>
    <version>4.0.0</version>
    <scope>provided</scope>
</dependency>

Different version DBAPI depends on different version of dbapi-plugin.jar, mapping as follows:

DBAPI version dbapi-plugin version
4.0.0 - 4.0.1 4.0.0

# Plugin Development

# Cache plugin development

New a java class extends com.gitee.freakchicken.dbapi.plugin.CachePlugin

import com.gitee.freakchicken.dbapi.common.ApiConfig;
import com.gitee.freakchicken.dbapi.plugin.CachePlugin;

import java.util.Map;

public class Cdemo extends CachePlugin {

    /**
     * Plugin name, for display on the page, prompts the user
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * Plugin function description for display on the page to prompt the user
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * Plugin parameter description, used to display on the page to prompt the user
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * init method, only execute once
     * for example, used to initialze collection pool
     */
    @Override
    public void init() {

    }

    /**
     * set data to cache
     *
     * @param config api configuration
     * @param requestParams request params
     * @param data   data to be cached
     * @param localPluginParam local plugin param
     */
    public void set(ApiConfig config, Map<String, Object> requestParams, Object data, String localPluginParam){

    }

    /**
     * clean cache, when update/delete/offline API, this method will be executed
     * 
     * @param config: api configuration
     * @param localPluginParam local plugin param
     */
    public void clean(ApiConfig config, String localPluginParam){

    }

    /**
     * get data from cache
     *
     * @param config: api configuration
     * @param requestParams: request params
     * @param localPluginParam local plugin param
     * @return
     */
    public Object get(ApiConfig config, Map<String, Object> requestParams, String localPluginParam){
        return null;
    }

}

init method used to initialize plugin, like initialize redis connection pool

get method used to get data from cache, first param is API configuration, the second param is request params

set method is a method to setting the cache and called when the executor performs. The first parameter is the api configuration, the second parameter is the requested parameter, the third parameter is the executor execution result, if the data transform plugin is configured, is the converted result

clean method used to clean cached data. When update/delete/offline API, this method will be executed.

# Transform plugin development

New a java class extends com.gitee.freakchicken.dbapi.plugin.TransformPlugin

import com.alibaba.fastjson.JSONObject;
import com.gitee.freakchicken.dbapi.common.ApiConfig;
import com.gitee.freakchicken.dbapi.plugin.TransformPlugin;

import java.util.List;

public class Tdemo extends TransformPlugin {

    /**
     * plugin name, will be displayed on web UI
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * plugin description, will be displayed on web UI
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * plugin local param, will be displayed on web UI
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }

    /**
     * init method, only execute once
     * 
     */
    public abstract void init() {
    }

    /**
     * how to transform data
     * @param data: Results data returned after the executor is executed. 
     * @param localPluginParam plugin local params
     * @return
     */
    public abstract Object transform(Object data, String localPluginParam) {
        return null;
    }
}

The data conversion logic is written in the transform method, where the first parameter is the result returned by the API execution, and the second parameter is the local parameter of the plugin.

# Alarm plugin development

New a class extends com.gitee.freakchicken.dbapi.plugin.AlarmPlugin

import com.gitee.freakchicken.dbapi.common.ApiConfig;
import com.gitee.freakchicken.dbapi.plugin.AlarmPlugin;

import javax.servlet.http.HttpServletRequest;

public class EmailAlarmPlugin extends AlarmPlugin {
    /**
     * init method, only execute once
     */
    @Override
    public void init() {

    }

    /**
     * how to alarm
     *
     * @param e           error
     * @param config      API configuration
     * @param request     request
     * @param localPluginParam  plugin local params
     */
    @Override
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }

    /**
     * plugin name, will be displayed on web UI
     *
     * @return
     */
    @Override
    public String getName() {
        return null;
    }

    /**
     * plugin description, will be displayed on web UI
     *
     * @return
     */
    @Override
    public String getDescription() {
        return null;
    }

    /**
     * plugin local param description, will be displayed on web UI
     *
     * @return
     */
    @Override
    public String getParamDescription() {
        return null;
    }
}

# Plugin registration

DBAPI plugin depends on java spi mechanism, you need to register plugin ：

  • Make directory named META-INF in resources, then make services directory in META-INF

  • Make file named com.gitee.freakchicken.dbapi.plugin.CachePlugin in META-INF/services directory, input java class name of your cache plugin in this file, one plugin one row.

  • Make file named com.gitee.freakchicken.dbapi.plugin.TransformPlugin in META-INF/services directory, input java class name of your transform plugin in this file, one plugin one row.

  • Make file named com.gitee.freakchicken.dbapi.plugin.GlobalTransformPlugin in META-INF/services directory, input java class name of your global transform plugin in this file, one plugin one row.

  • Make file named com.gitee.freakchicken.dbapi.plugin.AlarmPlugin in META-INF/services directory, input java class name of your alarm plugin in this file, one plugin one row.

# Plugin Description

# Plugin global parameters

global parameters defined in conf/plugin.properties file

  • If one plugin need to be used in different DBAPI system, plugin global parameters needed
  • Global parameters relates to plugin itself, none releation to API.For example, redis cache plugin need redis ip/port/password,these configurations are in conf/plugin.properties file.
  • If you have 2 DBAPI systems, like test system and production system. One redis cache plugin can be used by different DBAPI systems. Test DBAPI uses redis cache plugin with test redis configuration, production DBAPI uses redis cache plugin with production redis configuration.
  • Define plugin global parameters in conf/plugin.properties file, like ：
RedisCachePlugin.ip=127.0.0.1
RedisCachePlugin.port=6379
RedisCachePlugin.db=0
RedisCachePlugin.password=
  • Method for obtaining the value of plugin global parameter by java code：
import com.gitee.freakchicken.dbapi.plugin.PluginConf;
String ip=PluginConf.getKey("RedisCachePlugin.ip")

# Plugin local parameters

  • Local parameters relate to API, none releation to plugin itself

  • Local parameters configured from web UI when create/modify API

  • Take redis cache plugin for example, different API uses the same redis cache plugin, but different API needs different expiration time in redis, so plugin developer can define redis expiration time as the local parameters.

  • Take encryption plugin( transform plugin) for example, different API needs to encrypt different fields with the same encryption plugin, so plugin developer can define fields to be encrypted as the local parameters.

  • Take email alarm plugin for example, different API error needs to be sent to different recipient by email, so plugin developer can define recipient as the local parameters.

  • Method for obtaining the value of plugin local parameters:

// The local parameters of the plugin have been passed into the corresponding plugin method, and the parameter name is localPluginParam
// For example, the alarm method of the alarm plugin, the last parameter is the local plugin parameter.
    public void alarm(Exception e, ApiConfig config, HttpServletRequest request, String localPluginParam) {

    }

# Plugin log

If you need to print log in plugin, please use supper.logger

super.logger.debug("set data to cache");

# Plugin basic information

  • All plugins need to override getName getDescription getParamDescription methods which used to show plugin info on web UI

# Plugin deployment

  • Package the plugin maven project to jar file, then copy the jar file and dependency jar files to the lib folder of DBAPI, then restart DBAPI(If cluster mode, please copy jar files to each node)
  • If the plugin has global parameters, you need to introduce global parameters in conf/plugin.properties of DBAPI, then restart DBAPI(If cluster mode, please modify conf/plugin.properties of each node)

# Plugin code demo

code demo (opens new window)