Chapter 20. HowTo - Create a Client-Project for the OpenEngSB

20.1. Goal

This tutorial describes how to setup a client project for OpenEngSB using maven archetype

20.2. Time to Complete

If you are already familiar with the OpenEngSB about 30 minutes (This includes only the setup for the project). If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information.

20.3. Step 1 - Needed tools

You need to have following tools to be installed

20.3.1. Java Development Kit 6

First of all the JDK6 should be installed on the system and the JAVA_HOME variable should be set. (Java download). Also, make sure that the java-command is available in the PATH-variable

20.3.2. Maven 3

You will also need Maven 3 be installed on your system. (Maven download) Also, make sure that the maven-command is available in the PATH-variable

20.4. Step 2 - Using the archetype

The OpenEngSB provides an maven archetype to create a client project. To use it go into your target directory and type in a shell:

mvn openengsb:genClientProjectRoot

The script generates the result in the directory from where it was started

You will be asked to fill out following values (if no input is provided the default value is kept):

      Project Group Id [org.openengsb.client-project]:
      Project Artifact Id [openengsb-client-project]:
      Project Name [Client-Poject]:
      Project Version [1.0.0-SNAPSHOT]:
      Project Description [This is a client project for the OpenEngSB]:
      Project Url [http://www.openenbsb.org]:
      OpenEngSB version [1.2.0-SNAPSHOT]:
      OpenEngSB maven plugin Version [1.4.0-SNAPSHOT]:
      Plugin Assembly version [2.2-beta-5]:

You will be asked what the groupId, artifactId and a name of your client project should look like. You can also specify the OpenEngSB version you want to use, but it is recommended to use an up-to-date version. To check the current OpenEngSB version have a look at the Download section. It asks you to confirm the configuration and will create the project.

20.5. Step 3 - The result

If everything worked as expected you will get a client project having following structure:

.
`-- openengsb-client-project
      |-- assembly
      | |-- pom.xml
      |     `-- src
      |     `-- main
      | |-- descriptors
      | |   `-- bin.xml
      |     `-- filtered-resources
      | |-- etc
      | |   `-- org.apache.karaf.features.cfg
      | |-- features.xml
      |     `-- README.txt
      |-- core
      |   `-- pom.xml
      |-- docs
      | |-- homepage
      | | |-- pom.xml
      | |     `-- src
      | |     `-- site
      | |     `-- ...
      | |-- manual
      | | |-- pom.xml
      | |     `-- src
      | |     `-- ...
      |   `-- pom.xml
      |-- LICENSE
      |-- poms
      | |-- compiled
      | |   `-- pom.xml
      | |-- nonosgi
      | |   `-- pom.xml
      | |-- pom.xml
      |     `-- wrapped
      |     `-- pom.xml
      |-- pom.xml
      `-- README.md

You can find further information about these modules in the OpenEngSB-Manual

20.6. Step 4 - Install features

To install features to the project have a look at the file org.apache.karaf.features.cfg in assembly/src/main/filtered-resource/etc. Here you can define features to be registered by default or which feature should be installed on startup. To install your own features see the file features.xml in assembly/src/main/filtered-resource. E.G.: You want to add a module called clientproject-ui the core features add this to the features.xml

      <bundle>mvn:org.openengsb.clientproject.ui/clientproject-ui-web$\{project.version\}/war</bundle>

20.7. Step 5 - Start the Client-Project

To start the client-project, go to the command-window and type

mvn clean install openengsb:provision

Now you can enter "list" into the karaf console to check what features are installed and running

20.8. Step 6 - Shutdown

To shutdown, go to the command-window and type "shutdown" or press "Ctrl+D"