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 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. But if this tool requires a new domain it has to be created. This is also described in Chapter 22, How To Create an Internal Domain.
To take the burden of the developer creating the initial boilerplate code and configuration, a Maven archetype
is provided for creating the initial project structure. Furthermore, if the new connector is developed inside of
the OpenEngSB repository, a shell script can be found at etc/scripts/gen-connector.sh
for
further help in creating a new connector project.
It is not recommended to use the maven archetype directly, because the gen-connector.sh script executes additional tasks, like the renaming of the resulting project. Furthermore the shell script 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, which is not only parent of the connector, but also for the implementation of the domain and all other connectors of this domain.
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. Do not forget to check that the new connector is included in the modules section of the domain parent pom.
Calling the script should be done from the domain-specific directory. I.e. if your are developing a new
connector for the Notification-Domain your current directory should be domains/notification
.
Inside your favourite shell execute the script.
notification $ ../../etc/scripts/gen-connector.sh
The script tries to guess as much as possible from your current location and 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 domains/notification
directory:
Domain Name (is notification): <Enter>
Domain Interface (is NotificationDomain): <Enter>
Connector Name: twitter <Enter>
Version (is 1.0.0-SNAPSHOT): <Enter>
Project Name (is OpenEngSB :: Domains :: Notification :: Twitter): <Enter>
Only the connector name was set, everything else has been guessed correctly by the script. After this inputs
the Maven Archetype gets called and may ask you for further inputs. You can simply hit Return
each time, because the values have been already set by the script. If the script finishes successfully the new
connector project has been 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. Here additional bean setup and dependency injection can be configured.
The OpenEngSB has been built 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 validators,
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.