Chapter 17. Building with Maven
Abstract
Maven is an open source build system which is available from the Apache Maven project. This chapter explains some of the basic Maven concepts and describes how to set up Maven to work with Red Hat Fuse. In principle, you could use any build system to build an OSGi bundle. But Maven is strongly recommended, because it is well supported by Red Hat Fuse.
17.1. Maven Directory Structure
17.1.1. Overview
One of the most important principles of the Maven build system is that there are standard locations for all of the files in the Maven project. There are several advantages to this principle. One advantage is that Maven projects normally have an identical directory layout, making it easy to find files in a project. Another advantage is that the various tools integrated with Maven need almost no initial configuration. For example, the Java compiler knows that it should compile all of the source files under src/main/java and put the results into target/classes.
17.1.2. Standard directory layout
Example 17.1, “Standard Maven Directory Layout” shows the elements of the standard Maven directory layout that are relevant to building OSGi bundle projects. In addition, the standard locations for Blueprint configuration files (which are not defined by Maven) are also shown.
Example 17.1. Standard Maven Directory Layout
ProjectDir/
pom.xml
src/
main/
java/
...
resources/
META-INF/
OSGI-INF/
blueprint/
*.xml
test/
java/
resources/
target/
...It is possible to override the standard directory layout, but this is not a recommended practice in Maven.
17.1.3. pom.xml file
The pom.xml file is the Project Object Model (POM) for the current project, which contains a complete description of how to build the current project. A pom.xml file can be completely self-contained, but frequently (particular for more complex Maven projects) it can import settings from a parent POM file.
After building the project, a copy of the pom.xml file is automatically embedded at the following location in the generated JAR file:
META-INF/maven/groupId/artifactId/pom.xml
17.1.4. src and target directories
The src/ directory contains all of the code and resource files that you will work on while developing the project.
The target/ directory contains the result of the build (typically a JAR file), as well as all all of the intermediate files generated during the build. For example, after performing a build, the target/classes/ directory will contain a copy of the resource files and the compiled Java classes.
17.1.5. main and test directories
The src/main/ directory contains all of the code and resources needed for building the artifact.
The src/test/ directory contains all of the code and resources for running unit tests against the compiled artifact.
17.1.6. java directory
Each java/ sub-directory contains Java source code (*.java files) with the standard Java directory layout (that is, where the directory pathnames mirror the Java package names, with / in place of the . character). The src/main/java/ directory contains the bundle source code and the src/test/java/ directory contains the unit test source code.
17.1.7. resources directory
If you have any configuration files, data files, or Java properties to include in the bundle, these should be placed under the src/main/resources/ directory. The files and directories under src/main/resources/ will be copied into the root of the JAR file that is generated by the Maven build process.
The files under src/test/resources/ are used only during the testing phase and will not be copied into the generated JAR file.
17.1.8. Blueprint container
OSGi R4.2 defines a Blueprint container. Red Hat Fuse has built-in support for the Blueprint container, which you can enable simply by including Blueprint configuration files, OSGI-INF/blueprint/*.xml, in your project. For more details about the Blueprint container, see Chapter 12, OSGi Services.
17.2. BOM file for Apache Karaf
The purpose of a Maven Bill of Materials (BOM) file is to provide a curated set of Maven dependency versions that work well together, saving you from having to define versions individually for every Maven artifact.
The Fuse BOM for Apache Karaf offers the following advantages:
- Defines versions for Maven dependencies, so that you do not need to specify the version when you add a dependency to your POM.
- Defines a set of curated dependencies that are fully tested and supported for a specific version of Fuse.
- Simplifies upgrades of Fuse.
Only the set of dependencies defined by a Fuse BOM are supported by Red Hat.
To incorporate a Maven BOM file into your Maven project, specify a dependencyManagement element in your project’s pom.xml file (or, possibly, in a parent POM file), as shown in the following example:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project ...>
...
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!-- configure the versions you want to use here -->
<fuse.version>7.4.0.fuse-740036-redhat-00002</fuse.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.redhat-fuse</groupId>
<artifactId>fuse-karaf-bom</artifactId>
<version>${fuse.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
...
</project>
The org.jboss.redhat-fuse BOM is new in Fuse 7 and has been designed to simplify BOM versioning. The Fuse quickstarts and Maven archetypes still use the old style of BOM, however, as they have not yet been refactored to use the new one. Both BOMs are correct and you can use either one in your Maven projects. In an upcoming Fuse release, the quickstarts and Maven archetypes will be refactored to use the new BOM.
After specifying the BOM using the dependency management mechanism, it becomes possible to add Maven dependencies to your POM without specifying the version of the artifact. For example, to add a dependency for the camel-velocity component, you would add the following XML fragment to the dependencies element in your POM:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-velocity</artifactId> </dependency>
Note how the version element is omitted from this dependency definition.
