Chapter 22. How To Create an Internal Domain

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 5, Architecture of the OpenEngSB.

22.1. Prerequisites

In case it isn't known what a domain is and how it defines the interface and events for connectors, then Section 5.4, “OpenEngSB Tool Domains” is a good starting point.

22.2. Creating a new domain project

To get developers started creating a new domain a Maven archetype is provided for creating the initial project structure. Furthermore, if the new domain is developed in the OpenEngSB repository, a shell script can be found at etc/scripts/gen-domain.sh as further convenience.

22.2.1. Using the Maven Archetype

It is not recommended to use the maven archetype directly, because the gen-domain.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:

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

The following parameters have to be defined for the parent of the new domain, which is not only parent of the domain implementation, but also for all connectors of this domain.

  • groupId - the groupId of the project parent. Has to be "org.openengsb.domains.<yourDomain>".
  • artifactId - the artifactId of the project parent. Has to be "openengsb-domains-<yourDomain>-parent".
  • version - the version of the domain parent, which is usually equal to the current archetype version.
  • name - the name of the parent module. Has to be "OpenEngSB :: Domains :: <yourDomain> :: Parent"

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

  • implementationArtifactId - the implementation artifact id. Has to be "openengsb-domains-<yourDomain>-implementation".
  • package - the package for the source code of the domain implementation. Has to be "org.openengsb.domains.<yourDomain>".
  • implementationName - the name of the implementation module. Has to be "OpenEngSB :: Domains :: <yourDomain> :: Implementation"

Where <yourDomain> has to be replaced by your domain name, which is usually written in lower case, like e.g. 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.

22.2.2. Using the gen-domain.sh shell script

The script should be executed from the domains directory in your OpenEngSB repository.

domains $ ../etc/scripts/gen-domain.sh

You'll be asked to fill i a few variables the script needs to create the initial project structure. Based on your input, the script tries to gues 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 (is mydomain): test <Enter>
Version (is 1.0.0-SNAPSHOT): <Enter>
Prefix for project names (is OpenEngSB :: Domains :: Test): <Enter>

Only the domain name has been filled in, while the rest has been correctly guessed by the script. 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 by the script. If the script 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.

22.2.3. Project structure

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 besides simple stubs for the domain interface, the domain events interface and the domain provider also a resources folder, which contains 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 pax: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. E.g. the Maven Archetype already creates to 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 domains, this only means localization for a name and description of the domain itself.

22.3. Components

  1. 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.

  2. Domain event interface - This is the interface that the domain provides for its connectors to send events into the OpenEngSB. The event interface contains a raiseEvent(SomeEvent event) method for each supported event type.

  3. 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.

  4. Spring context - There are three services, that must be registered with the OSGi service-environment. First there is the domainprovider of course. 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 the OpenEngSB. The default implementation of this event interface simply forwards all events sent through the domain to the workflow service. But domains can also provide their own implementation of their event interface and add data to events or perform other tasks. There is a beanfactory 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 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 the OpenEngSB.

22.4. Connectors

For information regarding the implementation of connectors for the newly created domain see Chapter 21, How To Create an Internal Connector.