ExecutionUtils

Utility class for executing BeanShell scripts and operating-system commands. All methods are static.

Note

The runScript methods execute BeanShell scripts. BeanShell is a Java source interpreter that can execute Java syntax directly, making it ideal for dynamic automation logic.

Methods

runScript (from file)

Description:

Method	Return values	Description
runScript(File script)	Object[]	Executes a BeanShell script from a file and returns a three-element array.

• script: The .bsh file to execute.
• The returned Object[] has three elements:

Example:

package com.openkm;

import java.io.File;
import com.openkm.util.ExecutionUtils;

public class Test {

    public static void main(String[] args) {
        try {
            File script = new File("/home/openkm/test.bsh");
            Object[] result = ExecutionUtils.runScript(script);
            System.out.println("Return: " + result[0]);
            System.out.println("StdOut: " + result[1]);
            System.out.println("StdErr: " + result[2]);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

runScript (from string with system token)

Description:

Method	Return values	Description
runScript(String script, String systemToken)	Object[]	Executes a BeanShell script provided as a string, with the system token pre-injected into the script environment as the variable systemToken.

• script: The BeanShell script source code as a string.
• systemToken: The administrator token, made available inside the script as the variable systemToken.
• The returned Object[] has three elements: [0] return value, [1] stdout, [2] stderr.

Example:

package com.openkm;

import com.openkm.module.db.stuff.DbSessionManager;
import com.openkm.util.ExecutionUtils;

public class Test {

    public static void main(String[] args) {
        try {
            String systemToken = DbSessionManager.getInstance().getSystemToken();
            String script = "import com.openkm.api.OKMDocument;\n" +
                            "import com.openkm.util.ContextWrapper;\n" +
                            "OKMDocument doc = ContextWrapper.getContext().getBean(OKMDocument.class);\n" +
                            "System.out.println(doc.getProperties(systemToken, \"/okm:root/test.pdf\"));";
            Object[] result = ExecutionUtils.runScript(script, systemToken);
            System.out.println("StdOut: " + result[1]);
            System.out.println("StdErr: " + result[2]);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

runScript (from string with custom environment)

Description:

Method	Return values	Description
runScript(String script, Map<String, Object> env)	Object[]	Executes a BeanShell script provided as a string, pre-populating the script interpreter with all variables from the env map. This is the most flexible overload for passing custom context to scripts.

• script: The BeanShell script source code as a string.
• env: A map of variable names to values made available inside the script scope.
• The returned Object[] has three elements: [0] return value, [1] stdout, [2] stderr.

Example:

package com.openkm;

import com.openkm.module.db.stuff.DbSessionManager;
import com.openkm.util.ExecutionUtils;

import java.util.HashMap;
import java.util.Map;

public class Test {

    public static void main(String[] args) {
        try {
            Map<String, Object> env = new HashMap<>();
            env.put("systemToken", DbSessionManager.getInstance().getSystemToken());
            env.put("folderPath", "/okm:root/reports");

            String script = "System.out.println(\"Processing folder: \" + folderPath);";
            Object[] result = ExecutionUtils.runScript(script, env);
            System.out.println("StdOut: " + result[1]);
            System.out.println("StdErr: " + result[2]);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

runCmd (string, default timeout)

Description:

Method	Return values	Description
runCmd(String cmd)	CmdExecutionResult	Executes an operating-system command string using the system default execution timeout. The command is split on spaces; quoted arguments are handled correctly.

• cmd: The command line to execute. Quoted arguments containing spaces are supported.
• CmdExecutionResult contains:

Example:

package com.openkm;

import com.openkm.bean.CmdExecutionResult;
import com.openkm.util.ExecutionUtils;

public class Test {

    public static void main(String[] args) {
        try {
            CmdExecutionResult result = ExecutionUtils.runCmd("ls -la /home/openkm");
            System.out.println("Exit: " + result.getExitValue());
            System.out.println("StdOut: " + result.getStdout());
            System.out.println("StdErr: " + result.getStderr());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

runCmd (string, custom timeout)

Description:

Method	Return values	Description
runCmd(String cmd, long timeout)	CmdExecutionResult	Executes an operating-system command string with a custom timeout in milliseconds. If the process does not finish within the timeout it is killed.

• cmd: The command line to execute.
• timeout: Maximum execution time in milliseconds.

Example:

package com.openkm;

import com.openkm.bean.CmdExecutionResult;
import com.openkm.util.ExecutionUtils;

import java.util.concurrent.TimeUnit;

public class Test {

    public static void main(String[] args) {
        try {
            long timeout = TimeUnit.SECONDS.toMillis(30);
            CmdExecutionResult result = ExecutionUtils.runCmd("convert input.pdf output.png", timeout);
            if (result.getExitValue() != 0) {
                System.err.println("Command failed: " + result.getStderr());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

runCmd (string array)

Description:

Method	Return values	Description
runCmd(String[] cmd)	CmdExecutionResult	Executes an operating-system command provided as a pre-split string array, using the system default timeout. Use this overload when arguments already contain spaces or special characters that should not be re-split.

• cmd: The command and its arguments as separate array elements.

Example:

package com.openkm;

import com.openkm.bean.CmdExecutionResult;
import com.openkm.util.ExecutionUtils;

public class Test {

    public static void main(String[] args) {
        try {
            String[] cmd = { "cp", "/home/openkm/source.pdf", "/home/openkm/dest dir/copy.pdf" };
            CmdExecutionResult result = ExecutionUtils.runCmd(cmd);
            System.out.println("Exit: " + result.getExitValue());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

printErrorInfo

Description:

Method	Return values	Description
printErrorInfo(Logger srcLog, CmdExecutionResult er)	void	Logs the exit value, stdout, and stderr of a CmdExecutionResult at ERROR level using the provided logger. Useful for diagnosing failed command executions.

Example:

package com.openkm;

import com.openkm.bean.CmdExecutionResult;
import com.openkm.util.ExecutionUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Test {

    private static final Logger log = LoggerFactory.getLogger(Test.class);

    public static void main(String[] args) {
        try {
            CmdExecutionResult result = ExecutionUtils.runCmd("somecommand --arg");
            if (result.getExitValue() != 0) {
                ExecutionUtils.printErrorInfo(log, result);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}