Skip to main content

Writing Plugins

Writing Plugins​

A server plugin in ADITO is a Java class that extends AbstractPlugin. You must override the following methods:

  • public String getDescription()
  • public Object[] execute(Object[] pParameters, IPluginFacade pPluginFacade) throws PluginException

The getDescription method's return value is included in the server log if an uncaught error occurs during plugin loading or execution. This helps identify the plugin.

The execute method allows you to call other classes and libraries. It provides access to the logging backend and database layer via the PluginFacade. You can use methods like log, doDBRequest, and runJDitoProcess.

Example​

package de.adito.plugin;

import de.adito.aditoweb.common.jdito.plugin.*;
import de.adito.aditoweb.common.jdito.plugin.impl.AbstractPlugin;

/**
 * Demo Plugin
 */
public class DemoPlugin extends AbstractPlugin
{
    static
    {
        System.out.println("*************************");
        System.out.println("* Plugin Demonstration *");
        System.out.println("*************************");
    }

    public String getDescription()
    {
        return "DemoPlugin: Demonstrates plugin functionality";
    }

    public Object[] execute(Object[] pParameters, IPluginFacade pPluginFacade) throws PluginException
    {
        try
        {
        return new String[]{"Plugin result: " + pParameters[0].toString()};
        }
        catch (Exception ex)
        {
        // handle exception
        return new String[]{"Error"};
        }
    }
}

The static block is printed to the server log when the plugin is loaded. Once a plugin is loaded, you must restart the server to reload it.

Compile your plugin with the Java compiler and package the resulting .class file together with AbstractPlugin in a .jar file. Place the .jar file in lib/server/plugin in your ADITO distribution.

warning

Ensure AbstractPlugin resides in the path de/adito/aditoweb/common/jdito/plugin/impl inside the JAR. This path must match the package structure and must not be changed.

All external libraries used in your plugin must match the versions provided in the ADITO distribution. Additional dependencies must be added to the classpath.

Using PluginFacade Methods​

The execute method receives an instance of PluginFacade.

Logging​

You can use the log method on the PluginFacade to write messages to the server or client logs.

Available overloads:

  • log(Throwable pException, int pID, Object pDetails, boolean pShowDialog)

  • log(Throwable pException, Object pDetails, boolean pShowDialog)

  • log(Object pDetails, boolean pShowDialog)

  • pDetails: Any object; toString() is called on it. Arrays will be processed element-wise.

  • pShowDialog: Set to true to show a message to the client. The pDetails content is shown in the error dialog.

tip

Messages are written to the respective log files with log level R.

Logging Example​

pPluginFacade.log(ex, new String[]{"Detail1", "Detail2"}, true);

Result:

Z-00-N-0011-S Exception that caused the failure [ID 1]
Exception: java.lang.Exception [->] Message: Exception-Message
J-39-R-0000-S Plugin error [->] Detail1 [->] Detail2

Other overloads:

pPluginFacade.log(ex, "Detail", true);
pPluginFacade.log("Detail", true);
pPluginFacade.log(new String[]{"Detail1", "Detail2", "Detail3"}, true);

Database Access​

Use:

ArrayList doDBRequest(String pAlias, String[] pSQLStatements, int pStart, int pCount, boolean pGetMetaData, boolean pWithLobContent, boolean pWithRowCount)

  • pAlias: database alias

  • pSQLStatements: array of SQL statements

  • pStart / pCount: define result window

  • pGetMetaData, pWithLobContent, pWithRowCount: set to false

  • return: Returned results are in ArrayList form. SELECT results contain Object arrays for each row.

Example​

String[] sql = {
  "select count(*) from org",
  "select orgid, orgname from org where orgid < 1010"
};
ArrayList result = pPluginFacade.doDBRequest("AO_DATEN", sql, 0, -1, false, false, false);
return result.toArray();

Calling JDito Processes​

Use:

String runJDitoProcess(String pProcessName, Map pLocalVariables)
  • pProcessName: name of the process
  • pLocalVariables: parameter map, accessible via $local.<key>
  • return: the return value of the JDito process, typically set using JDito's result.string() or similar methods.

Example Plugin Code​

HashMap<String, String> map = new HashMap<>();
map.put("Param1", "Value1");
map.put("Param2", "Value2");
String result = pPluginFacade.runJDitoProcess("pluginprocess", map);
return new String[]{result};

Example JDito Process​

var p1 = vars.getString("$local.Param1");
var p2 = vars.getString("$local.Param2");
var result = "First: " + p1 + ", Second: " + p2;
result.string(result);

Example Invocation​

var url = "file:///E:/java/DemoPlugin/DemoPlugin.jar";
var clazz = "de.adito.plugin.DemoPlugin";

var pluginResponse = plugin.run(url, clazz, null);

var str = pluginResponse[0];
question.showMessage(str);