| = ESA Maven Plugin |
| |
| This page describes the `esa-maven-plugin` version 1.0.0 which is available from Maven Central. |
| |
| The ESA Maven Plugin provides the ability to generate ESA archives using Maven. |
| The ESA archive format is defined in the Subsystems Service Specification which was part of http://www.osgi.org/Specifications/HomePage[OSGi Enterprise R5]. |
| An ESA archive can optionally contain an Subsystem manifest (`SUBSYSTEM.MF`). |
| This can be added in one of two ways |
| |
| . Hand written and added into the archive. |
| . Generated based on pom configuration. |
| |
| |
| == Using the Plugin |
| |
| The plugin is included by as follows: |
| |
| .... |
| <project> |
| ... |
| <packaging>esa</packaging> <!-- set packaging type to esa --> |
| |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.aries</groupId> |
| <artifactId>esa-maven-plugin</artifactId> |
| <version>1.0.0</version> |
| <extensions>true</extensions> |
| </plugin> |
| </plugins> |
| </build> |
| </project> |
| .... |
| |
| By default it will not generate a manifest, so in the above example it will attempt to copy a pre-defined `SUBSYSTEM.MF` from `src/main/resources/META-INF`. |
| If that file does not exist, then no Subsystem manifest will be included. |
| |
| |
| == Generating an SUBSYSTEM.MF |
| |
| The following example `pom.xml` shows how to get the plugin to generate an `SUBSYSTEM.MF` based on the pom configuration: |
| |
| .... |
| <project> |
| <modelVersion>4.0.0</modelVersion> |
| |
| <groupId>org.something</groupId> |
| <artifactId>esa-maven-plugin-test</artifactId> |
| <version>1.0.0-SNAPSHOT</version> |
| <packaging>esa</packaging> |
| |
| <dependencies> |
| <!-- Put some dependencies in here --> |
| </dependencies> |
| |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.aries</groupId> |
| <artifactId>esa-maven-plugin</artifactId> |
| <version>1.0.0</version> |
| <extensions>true</extensions> |
| <configuration> |
| <generateManifest>true</generateManifest> |
| </configuration> |
| </plugin> |
| </plugins> |
| </build> |
| </project> |
| .... |
| |
| The pom to subsystem manfiest header mapping is as follows: |
| |
| * Pom <groupId/>.<artifactId/> \-> Subsystem-SymbolicName |
| * Pom <name/> \-> Subsystem-Name |
| * Pom <version/> \-> Subsystem-Version (cleaned up for OSGi) |
| * Pom <description/> \-> Subsystem-Description |
| * Pom <dependencies/> \-> Subsystem-Content |
| |
| == Overriding Subsystem-SymbolicName |
| |
| The subsystem symbolic name defaults to the ${project.groupId}.${project.artifactId}. |
| The following shows how to override this: |
| |
| <configuration> |
| <instructions> |
| <Subsystem-SymbolicName>${project.artifaceId}</Subsystem-SymbolicName> |
| </instructions> |
| </configuration> |
| |
| == Including bundles in the archive |
| |
| By default, the archive will only include the direct dependencies of the project. |
| The `<archiveContent/>` element can be used to control the archive artifact contents. |
| The following shows how to include all direct and transitive dependencies. |
| |
| <configuration> |
| <archiveContent>all</archiveContent> |
| </configuration> |
| |
| The following shows how to exclude all dependencies from the archive. |
| This is useful if you just want the subsystem definition and will use a bundle repository to provision the bundles during deployment. |
| |
| <configuration> |
| <archiveContent>none</archiveContent> |
| </configuration> |
| |
| The following specifies the default of including only the direct dependencies (assumes the subsystem contents and direct dependencies are the same). |
| |
| <configuration> |
| <archiveContent>content</archiveContent> |
| </configuration> |
| |
| == Content Bundle Start Ordering |
| |
| By default, the Subsystem runtime can start content bundles in any order. |
| The OSGi start level service is not applicable to subsystems. |
| You can specify the start order of the bundles based on the order in which they're expressed as dependencies in the maven pom using the following: |
| |
| <configuration> |
| <startOrder>dependencies</startOrder> |
| </configuration> |
| |
| == Including an Existing Subsystem manifest |
| |
| If you don't wish to generate the Subsystem manifest based on the pom configuration, you can add an existing one as follows: |
| |
| <configuration> |
| <subsystemManifestFile>${basedir}/src/main/resources/OSGI-INF/SUBSYSTEM.MF</subsystemManifestFile> |
| </configuration> |
| |
| == Including Other Headers |
| |
| You can add any other headers in addition to those calculated from the pom configuration. |
| For example, the following specifies the Subsystem Use-Bundle header and sets the Subsystem-Type to be a feature: |
| |
| <instructions> |
| <Use-Bundle>org.apache.aries.test.Bundle;version=1.0.0-SNAPSHOT</Use-Bundle> |
| <Subsystem-Type>osgi.subsystem.feature</Subsystem-Type> |
| </instructions> |