This chapter describes how to implement a domain for the OpenEngSB environment. A domain provides a common interface and common events and thereby defines how to interact with connectors for this domain. For a better description of what a domain exactly consists of, take a look at the architecture guide Chapter 7, Architecture of the OpenEngSB.
In case it isn't known what a domain is and how it defines the interface and events for connectors, then Section 7.4, “OpenEngSB Tool Domains” is a good starting point.
To get developers started creating a new domain a Maven archetype is provided for creating the initial project
structure. The
openengsb-maven-plugin
(see Section 27.7.1, “openengsb-maven-plugin”) or the
etc/scripts/gen-domain.sh
script (which only wraps the invocation of the plugin) simplifies
the creation of a domain.
It is not recommended to use the maven archetype directly, because the genDomain 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 domain. It is not solely parent of the domain implementation, but parent of all connectors of this domain too.
The following parameters have to be defined for the implementation of the new domain.
Where <yourDomain> has to be replaced by your domain name which is usually written in lower case, i.e. report
for the report domain.
Note that the archetype will use the artifactId to name the project, but the OpenEngSB convention is to use the domain name. Therefore you will have to rename the resulting project. Do not forget to check that the new domain is included in the modules section of the domains pom.
Simply invoke mvn openengsb:genDomain
from the domains directory in your OpenEngSB
repository (alternatively the etc/scripts/gen-domain.sh
script can be used which invokes the
openengsb-maven-plugin for you).
domains $ mvn openengsb:genDomain
You'll be asked to fill in a few variables which are needed to create the initial project structure. Based on
your input, the mojo tries to guess further values. Guessed values are displayed in brackets. If the guess is
correct, simply acknowledge with Return
. As example, the following output has been recorded
while creating the Test domain:
Domain Name [mydomain]: test <Enter>
Version [1.0.0-SNAPSHOT]: <Enter>
Prefix for project names [OpenEngSB :: Domains :: Test]: <Enter>
Only the domain name has been filled in, while the rest has been correctly guessed. After
giving the inputs, the Maven archetype gets executed and may ask for further inputs. You can simply hit
Return
, as the values have been already correctly set. If the mojo finishes
successfully two new Maven projects, the domain parent and domain implementation project, have been created and
setup with a sample implementation for a domain.
The newly created domain should have the exact same structure as the following listing:
-- implementation | -- pom.xml | -- src | -- main | | -- java | | -- org | | -- openengsb | | -- domains | | -- mydomain | | -- MyDomain.java | | -- MyDomainEvents.java | | -- MyDomainProvider.java | -- resources | -- META-INF | | -- spring | | -- mydomain-context.xml | -- OSGI-INF | -- l10n | -- bundle_de.properties | -- bundle.properties -- pom.xml
The project contains stubs for the domain interface, the domain events interface and the domain provider and a resources folder with the spring setup and property files for internationalization.
Although the generated domain does in effect nothing, you can already start the OpenEngSB for testing with
mvn clean install openengsb:provision
and the domain will be automatically be picked up and started.
The spring setup in the resources folder already contains the necessary setup for this domain to work in the OpenEngSB environment. Furthermore the default implementation proxies for the domain interface, which forwards all service calls to the default connector for the domain and the default implementation of the domain event interface, which forwards all events to the workflow service of the OpenEngSB are configured.
Each OpenEngSB bundle (core, domain, connector) has been designed with localization in mind. The Maven
Archetype already creates 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 it own
properties files. For domains, this only means localization for a name and description of the domain
itself.
Domain interface - This is the interface that connectors of that domain must implement. Operations that connectors should provide, are specified here. Events that are raised by this Domain in unexpected fashion (e.g new commit in scm system) are specified on the Interface. The Raise Annotation and the array of Event classes it takes as an argument are used. If the Raise annotation is put on a method the events that are specified through the annotation are raised in sequence upon a call.
Domain event interface - This is the interface the domain provides for its connectors to send events
into OpenEngSB. The event interface contains a raiseEvent(SomeEvent event)
method for each
supported event type.
Domain Provider - The domain provider is a service that provides information about the domain itself. It is used to determine which domains are currently registered in the environment. There is an abstract class, that takes over most of the setup.
Spring context - There are three services, that must be registered with the OSGi service-environment. First, there is the Domain Provider. Moreover, the domain must provide a kind of connector itself since it must be able to handle service calls and redirect it to the default-connector specified in the current context. And finally the domain provides an event interface for its connectors which can be used by them to send events into OpenEngSB. The default implementation of this event interface simply forwards all events sent through the domain to the workflow service. However, domains can also provide their own implementation of their event interface and add data to events or perform other tasks. There is a bean factory that creates a Java-Proxy that can be used as ForwardService both for the forwarding of service calls from domain to connector and for the forwarding of events to the workflow service. The service call to ForwardService looks up the default-connector for the specified domain in the current context and forwards the method-call right to it. The event forward service simply forwards all events to the workflow service of OpenEngSB.
For information regarding the implementation of connectors for the newly created domain see Chapter 28, How To Create an Internal Connector.