Implementing a Custom Connector (General)

This chapter describes how to implement a custom connector.

Prerequisites

We assume that you are familiar with Java and with building Java projects and that Ant and a Java compiler are installed and in your path.

Documentation

To understand this issue, we recommend that you read these chapters:

DirX Identity Integration Framework Guide

The chapter Java Connector Integration Framework provides information about the interfaces a connector must implement and about its configuration and deployment.

JavaDoc

For the Java documentation of the interfaces, see the folder Documentation/DirXIdentity/ConnFrameWork on the product DVD.

The package siemens.dxm.connector.framework.util provides some helper utilities like serialization of SPML classes and response creation.

Note that most of the classes reflecting SPML/DSML are generated from the SPML schemata. Therefore, the inline java documentation of these classes does not help. For understanding them, please read the XML schemata and check request and response samples.

Training

We do not provide any special training or webinars for this issue.

Examples

For a sample connector, see the classes in the folder SampleConnector/java on the product DVD.

Hints, Tips and Tricks

This section provides additional hints.

Test

We recommend testing the connector outside of IdS-J with a JUnit Test from within a Java IDE such as Eclipse. For start-up, you can use the same project dxmTestMapping that is mentioned in the section in this guide on hints for provisioning workflow extensions. You don’t need all the included jar files, but that does not matter for development.

Test using a standalone job configuration reading requests from a file. Change the following template to your requirements regarding file locations and connector configuration:

<job>
    <controller       className="siemens.dxm.connector.framework.DefaultControllerStandalone">
        <logging level="9" filename="yourFolder/trace.txt">
        </logging>
    </controller>

    <connector
        role="reader"
        name="SPML file reader"
        className="siemens.dxm.connector.framework.SpmlFileReader">
        <connection type="SPML" filename="yourFolder/request.xml">
        </connection>
        <property name="validate" value="false"/>
    </connector>

    <connector
        role="connector"
        className="siemens.dxm.connector.sample.SampleConnector"
        name="Sample connector">
    	<connection type="file"            filename="yourFolder/response.xml"
            >
            <property name="validate" value="false"/>
    	</connection>
    </connector>

    <connector
        role="responseWriter"
        name="SPML File writer"
        className="siemens.dxm.connector.framework.test.SpmlTestWriter">
        <connection type="SPML"
            filename="yourFolder/receivedRsp.xml">
            <property name="referencefile"
                value="yourFolder/referenceRsp.xml"
            />
        </connection>
    </connector>
</job>

For a sample on how to run this configuration as a JUnit test, see one of the test classes of the dxmTestMapping project; for example, TestSample.

Use several SPML request files for testing. In order to have more than one request in a file, XML requires a root element. You can use the SPML <batchRequest> for this purpose, but SPML allows only a restricted set of requests within the batch. Especially, the batch must not contain a <searchRequest>. Therefore, the connector framework supports a proprietary extension: the root element <test> allows all types of SPML requests and responses.

Timeout

Workflows might be cancelled due to timeout or a server shutdown. In this case, the server performs a graceful abort and first informs all running worker threads., the server stops the threads after the grace period is over.

The job controller (also called the join engine) handles the cancel indications: it checks before it processes the next entry and stops when cancel has been requested.

Normally, connectors are not concerned with these issues unless they perform operations where they need to wait for another entity; for example, network operations or a batch or system script. In these cases, they should limit waiting time and check whether the activity has been cancelled. They can do this by calling the isCancelled method on the task context.

A connector should implement the interface siemens.dxm.connector.framework.DxmContext. The job controller passes the job context via its setContext() method. The connector can get the task context by

TaskContext taskContext = (TaskContext)context.get(TaskContext.class)

The task context holds the flag indicating an abort. You can check the flag as shown in the following code snippet:

if (((taskContext != null) && taskContext.isCancelled())
        || Thread.currentThread().isInterrupted()) {
    // stop and return to job controller
}

A hard stop of the thread is indicated by the interrupted flag of the thread. Never ignore InterruptedExceptions! Return immediately to the controller. Make sure you never reset either flag!