ConnectorLib Java 25.1
ConnectorLib Java SDK Programming Guide

# Implement Custom Actions

You can implement custom actions in a ConnectorLib Java connector.

Action | Description | Method to override
--- | --- | ---
`action=MyAction` | Perform custom actions on a repository. | `Custom`

To implement custom actions, the file `Autonomy_JNI.dll` (`libAutonomy_JNI.so` on non-Windows platforms) is required. This is provided in the SDK. If you implement the `custom` action but this library is not present, the following message is logged in the connector's application log, and the custom feature is disabled:

           50-Warning: Library Autonomy_JNI not loaded - 'custom' feature will be disabled

To implement a custom action, override the `custom` method on the `ConnectorBase` interface.

The ``custom`` method is passed the name of the action that was called in the request. The name is always in upper case, because action names are case-insensitive. You can use the `custom` method to handle as many action names as necessary, however the action names `FETCH`, `VIEW`, `GETURI`, `GETSTATUS`, and so on, are reserved by the connector for the standard actions.

The `custom` method is also passed a `CustomTask` object. The `CustomTask` object provides access to a request object which provides all of the action parameters. You can obtain the request object by calling the method `getRequest()` on the `CustomTask` object. To retrieve a single parameter call the method `getParameter(parameterName)` on the request object, or to retrieve a list of all parameters use the method `getParameters()`. These methods return parameter objects. To obtain the name and value of a parameter, call the methods `getName()` and `getValue()` on the parameter object. You can also use the method `getValue(defaultValue)` to read a parameter value and use a default value if the parameter is not set.

NOTE: All actions require a configuration file section name for the action to run. For a synchronous custom action, this is taken from the `configsection` parameter in the request (for example `MyActionSection` in the request `action=MyAction&configsection=MyActionSection`). If `configsection` is not set the connector uses the value of the `sectionname` parameter. If neither of these action parameters are set the connector uses the section name `Default`. In this case, the connector logs the following warning:

`WARNING: Custom action is not associated with a configuration section, using [Default] section`

The section name is available through the `CustomTask` object. Standard operations that read the configuration file use the correct section automatically.

Your code must use the parameters from the request to perform the action and populate the action response. You can obtain the response object by calling the method `getResponse()` on the `CustomTask` object. Set the value of XML elements in the response by calling the method `setValue(elementName, value)` on the response object.

You can add attributes and nested elements to the action response using XPath-like expressions with element indexes. For example:

           Response.setValue("document[0]/metadata[7]/@name", "MyField");

Your implementation of the custom method should return `false` only if the action name is not supported. In all other cases, return `true`. If another failure occurs then throw an exception from the `custom` method, giving the reason for the failure.

The following sample code shows how a custom action might be implemented for a basic connector. A Java source file with this sample code is provided in the SDK (`CustomAction.java`).

           public boolean custom(String actionName, CustomTask task) throws Throwable
           {
               if (actionName.equalsIgnoreCase("MyAction"))
               {
                   task.getLog().full("Custom action " + actionName + " called");

                   List parameters = task.getRequest().getParameters();
                   for (int ii = 0; ii < parameters.size(); ++ii)
                   {
                       Parameter param = (Parameter)parameters.get(ii);
                       task.getLog().full("  Parameter: " + param.getName() + "="
                                                + param.getValue());
                   }

                   task.getResponse().setValue("result", "42");
                   return true;
               }
               else
               {
                   return false;
               }
           }

Copyright 2024 Open Text
Version 25.1 | Last updated January 2025

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery ConnectorLib Java 25.1

Topic Title: Implement Custom Actions