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.
In case it isn't known what a tool domain is and how it defines the interface for the tool connector then Section 12.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 37, How To Create an Internal Domain.
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 Section 35.7.1, “openengsb-maven-plugin”)
(or the etc/scripts/gen-connector.sh
script, which wraps the invocation of the maven plugin)
which simplifies the creation of a connector project from the archetype. It should be used for assisted creation
of a new connector project.
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:
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.
The following parameters have to be defined for the domain of the new connector.
The following parameters have to be defined for the connector.
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.
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.
The newly created connector project should have the exact same structure as the following listing:
-- pom.xml -- src -- main -- java | -- org | -- openengsb | -- domains | -- notification | -- twitter | -- internal | | -- MyServiceImpl.java | | -- MyServiceInstanceFactory.java | -- MyServiceManager.java -- resources -- META-INF | -- spring | -- connector-context.xml -- OSGI-INF -- l10n -- bundle_de.properties -- bundle.properties
The MyServiceImpl
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 MyServiceManager
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
MyServiceManager
class extends a common base class
AbstractServiceManager
. In addition the AbstractServiceManager
also
persists the configuration of each connector, so that the connector instances can be restored after a system
restart.
The spring 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.