Implementing the Adapter Interface

All adapters use the de.softproject.integration.adapter.core.Adapter interface and the default constructor (without parameters) to create the main class. The abstract de.softproject.integration.adapter.core.BaseAdapter class contains a base implementation to get the adapter status and to access the project directory.

Defining Adapter Metadata

To define adapter metadata the annotation @AdapterDescription is used. The following fields must be set:

Field	Description	Mandatory
`category`	Technical adapter category	yes
`description`	Description of the adapter's purpose	yes
`displayName`	Displayed adapter name	yes
`version`	Adapter version with the following format: `major.minor.patch` (e.g. `1.0.0`)	yes
`configurationBeanClass`	Type of the `ConfigurationBean`, if the adapter requires parameters. If the adapter class contains the configuration, no values have to be set here.	no

Using BaseAdapter

This base class contains protected methods for accessing the adapter status and the ProjectExplorer. The basic implementation assumes that the configuration is made within the adapter class, which means that the adapter parameters are defined in the class itself. If you want to use your own class for the adapter configuration, the method getConfigurationBean must be overwrite as described in the section Defining Adapter Metadata.

Using the Adapter Interface

Create a new adapter class that implements the interface de.softproject.integration.adapter.core.Adapter.
Use the default constructor. This X4 class will be instantiated via default constructor at runtime of the X4 ESB.
The methods init(), cleanup() and getConfigurationBean() are created and the required packages are imported. With this constructor, the following elements are created:
- public void cleanup(): This method always cleans up after the execution of the operation method and closes resources that have been allocated by the adapter instance.
- public void init(Status arg0, long arg1): After creating the adapter instance, a status instance will be created and will be handed over to the adapter with the init() method call. Parameter arg0 specifies an object's adapter instance to set a status; parameter arg1 specifies the adapter instance (within the code).
  When executed, the adapter can manipulate its status instance within its do… methods, and this state will be evaluated by the X4 ESB.
- public Object getConfigurationBean(): Returns an instance of the configuration bean containing setter methods for setting configuration parameters. Adapter instances can access configuration parameters via the configuration bean object.
Create a status variable and assign an instance status.
Create a configuration bean object (see Creating the Configuration Bean), and use ingetConfigurationBean() as return value.
The basic framework for the adapter main class is now ready.

Example

JAVA

import java.nio.charset.StandardCharsets;
import de.softproject.integration.adapter.annotations.AdapterDescription;
import de.softproject.integration.adapter.annotations.AdapterOperation;
import de.softproject.integration.adapter.annotations.AdapterParameter;
import de.softproject.integration.adapter.core.AdapterException;
import de.softproject.integration.adapter.core.AdapterParameterDataType;
import de.softproject.integration.adapter.core.BaseAdapter;
import de.softproject.integration.util.x4documents.MimeTypeUtils;
import de.softproject.integration.util.x4documents.X4Document;
import de.softproject.integration.util.x4documents.X4DocumentFactory;

/**
 * This is a simple Adapter showing how Adapters are declared in the
 * X4-BPMS.<br>
 * An adapter needs some Annotation to be recognized by the X4-System:<br>
 * <ul>
 * <li>{@link AdapterDescription}: Mandatory for making an Adapter visible. It
 * describes the metadata of the adapter</li>
 * <li>{@link AdapterParameter}: Mandatory for Parameters. They will be mapped
 * to the corresponding setter Method. It must match the parameter name.
 * <li>{@link AdapterOperation}: Mandatory for Operations. It describes the
 * metadata for an adapter operation
 * </ul>
 */
@AdapterDescription(category = "Demo", description = "Say Hello...", displayName = "HelloWorld", version = "1.0.0")
public class HelloWorldAdapter extends BaseAdapter {

    @AdapterParameter(dataType = AdapterParameterDataType.STRING, description = "say hello to", optional = true)
    private String name = "default";

    @AdapterOperation(name = "HelloWorld")
    public X4Document sayHelloWorld(X4Document input) {
        return X4DocumentFactory.createX4Document("Hello World", StandardCharsets.UTF_8.name(),
                MimeTypeUtils.TEXTPLAIN);
    }

    @AdapterOperation(name = "HelloTo")
    public X4Document sayHelloTo(X4Document input) throws AdapterException {
        if (name == null || "".equals(name)) {
            throw new AdapterException(123, "Parameter \"name\" ist nicht gesetzt...");
        }
        getStatus().setOk();
        return X4DocumentFactory.createX4Document("Hello " + name, StandardCharsets.UTF_8.name(),
                MimeTypeUtils.TEXTPLAIN);
    }

    public void setName(String name) {
        this.name = name;
    }
}