Chapter 34. How To Create an Internal Connector

This chapter describes how to implement a connector for the OpenEngSB environment. A connector is an adapter between an external tool and the OpenEngSB environment. Every connector belongs to a domain which defines the common interface of all its connectors. This means that the connector is responsible to translate all calls to the common interface to the externally provided tool.

34.1. Prerequisites

In case it isn't known what a tool domain is and how it defines the interface for the tool connector then Section 5.4, “OpenEngSB Tool Domains” is a good starting point. If there's already a matching domain for this tool it is strongly recommended to use it. If the tool requires a new domain to be created relevant information can be found in Chapter 35, How To Create an Internal Domain.

34.2. Creating a new connector project

To take burden off the developer of creating the initial boilerplate code and configuration, a Maven archetype is provided for creating the initial project structure. Furthermore we provide the openengsb-maven-plugin (see ???) (or the etc/scripts/gen-connector.sh script, which wraps the invocation of the maven plug-in) which simplifies the creation of a connector project from the archetype. It should be used for assisted creation of a new connector project.

34.2.1. Using the Maven Archetype

It is not recommended to use the maven archetype directly, because the genConnector goal of the openengsb-maven-plugin executes additional tasks, I.e. renaming of the resulting project. Furthermore, it tries to make sure that the new project is consistent with the naming conventions of the OpenEngSB project.

The following parameters have to be specified to execute the correct archetype:

  • archetypeGroupId - the groupId of the OpenEngSB connector archetype.
  • archetypeArtifactId - the artifactId of the OpenEngSB connector archetype.
  • archetypeVersion - the current version of the OpenEngSB connector archetype.

The following parameters have to be defined for the parent of the new connector. It is not solely parent of the connector itself, but parent of the implementation of the domain and all other connectors of this domain too.

  • parentArtifactId - the artifactId of the project parent.

The following parameters have to be defined for the domain of the new connector.

  • groupId - the groupId of the domain.
  • domainArtifactId - the artifactId of the domain.

The following parameters have to be defined for the connector.

  • artifactId - the connector artifact id. Has to be "openengsb-domains-<yourDomain>-<yourConnector>".
  • version - the package for the source code of the domain implementation. Has to be "org.openengsb.domains.<yourDomain>".
  • domainInterface - The name of the domain interface.
  • parentPackage - The package in which the domain interface can be found.
  • package - the package for the connector code. Usually <parentPackage>.<yourConnector> is used.
  • name - the name of the implementation module. Has to be "OpenEngSB :: Domains :: <yourDomain> :: <yourConnector>"

Where <yourDomain> has to be replaced by your domain name and <yourConnector> has to be replaced by the respective connector name.

Note that the archetype will use the artifactId to name the project, but the OpenEngSB convention is to use the connector name. Therefore you will have to rename the resulting project (however if you use the genConnector mojo, this renaming will be performed automatically). Do not forget to check that the new connector is included in the modules section of the domain parent pom xml file.

34.2.2. Using mvn openengsb:genConnector

Simply invoke mvn openengsb:genConnector from the connector directory (connector/) (alternatively the etc/scripts/gen-connector.sh script can be used which invokes the openengsb-maven-plugin for you).


        connector $ mvn openengsb:genConnector
      

The mojo tries to guess as much as possible from your previous input. Guessed values are displayed in brackets. If the guess is what you want, simply acknowledge with Return. The following output has been recorded by executing the script in the connector/ directory:

Domain Name [domain]: notification <Enter>
Domain Interface [NotificationDomain]: <Enter>
Connector Name [myconnector]: twitter <Enter>
Version [1.0.0-SNAPSHOT]: <Enter>
Project Name [OpenEngSB :: Domains :: Notification :: Twitter]: <Enter>

Only the domain and connector name was set, everything else has been guessed correctly. After these inputs are provided the Maven Archetype gets called and may ask you for further inputs. You can simply hit Return each time to acknowledge standard values. If it finishes successfully the new connector project is created and you may start implementing.

34.3. Project Structure

The newly created connector project should have the exact same structure as the following listing:

-- src
|  -- main
|     -- java
|        -- org
|           -- openengsb
|              -- connector
|                 -- [myconnector]
|                    -- internal
|                    |  -- [MyConnector]Connector.java
|                    |  -- [MyConnector]ConnectorProvider.java
|                    |  -- [MyConnector]InstanceFactory.java
|     -- resources
|        -- OSGI-INF
|           -- blueprint
|              -- [myconnector]-[mydomain]-context.xml
|           -- l10n
|              -- bundle.properties
|              -- bundle_de.properties
|           -- bundle.info
-- pom.xml

The MyServiceConnector class implements the interface of the domain and thus is the communication link between the OpenEngSB and the connected tool. To give the OpenEngSB (and in the long run the end user) enough information on how to configure a connector, the MyServiceInstanceFactory class provides the OpenEngSB with meta information for configuring and functionality for creating and updating a connector instances. The MyServiceConnectorProvider class connects connector instances with the underlying OSGi engine and OpenEngSB infrastructure. It exports instances as OSGi services and adds necessary meta information to each instance. Since the basic functionality is mostly similar for all service managers, the MyServiceConnectorProvider class extends a common base class AbstractConnectorProvider. In addition the AbstractConnectorProvider also persists the configuration of each connector, so that the connector instances can be restored after a system restart.

The blueprint setup in the resources folder contains the setup of the service manager. Additional bean setup and dependency injection can be configured there.

The OpenEngSB has been designed with localization in mind. The Maven Archetype already generates two bundle*.properties files, one for English (bundle.properties) and one for the German (bundle_de.properties) language. Each connector has to provide localization through the properties files for service and attributes text values. This includes localization for names, descriptions, attribute validation, option values and more. For convenience the BundleStrings class is provided on all method calls where text is needed for user representation for a specific locale.

34.4. Integrating the Connector into the OpenEngSB environment

The connector provided is responsible for the integration of the connector into the OpenEngSB infrastructure. The correct definition of this service is critical.