1.4. Generated Artifacts

As a rule of thumb, a maven module should only generate a single artifact. This means that if your maven module is generating multiple jars, zips or features for example, you should split them into different modules unless there is a strong reason not to do so. Special artifacts such as sources, tests and poms do not take part in this restriction.

Here we seek to provide some information on the accepted formats for pentaho generated artifacts and how to properly configure and deal with them.

Jar

Common JAR (Java ARchive) is a package file format typically used to aggregate many Java class files and associated metadata and resources (text, images, etc.) into one file for distribution. The maven-jar-plugin should be used to generate this type of artifact and no configuration other than declaring <packaging>jar</packaging> in the pom file should be necessary for most scenarios.

OSGI Bundle

To create OSGI bundles we make use of the maven-bundle-plugin. If you have properly declared Pentaho parent poms as the parent of your project all you have to do is declare that your project has <packaging>bundle</packaging>. This will allow maven-bundle-plugin to generate the MANIFEST.MF and package your project.

If there is a need to add or override configuration you can do it by extending the plugin and adding the configurations you need.

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <configuration>
    <instructions>
      <Export-Package>org.foo.myproject.api</Export-Package>
      <Import-Package>org.foo.otherproject,*</Import-Package>
    </instructions>
  </configuration>
</plugin>

Check maven-bundle-plugin for documentation.

Karaf Feature

This section will be updated after http://jira.pentaho.com/browse/BACKLOG-19161 is implemented. For now, please do your best to follow the next guidelines.

Add a profile at the top level of your project and a pluginManagement section for the karaf-maven-plugin

<profile>
  <!-- This profile generates a feature file to deploy in karaf. -->
  <id>feature-generation</id>
  <activation>
    <file>
      <exists>${basedir}/src/main/feature</exists>
    </file>
  </activation>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</profile>

<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
        <version>${karaf-maven-plugin.version}</version>
        <extensions>true</extensions>
        <configuration>
          <aggregateFeatures>${karaf-maven-plugin.aggregateFeatures}</aggregateFeatures>
        </configuration>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

This configuration will soon be added in a form somewhat similar to this to the Parent Poms.

Also try to:

• Only manually define the parts of the feature file that can not be determined automatically. Currently we need to manually define bundles that require a custom deployer (e.g. platform-plugin-deployer, pentaho-webjars) and depending features that are not published in their own artifact. If you manually define a dependency in the feature file, make sure to also include that dependency, with scope provided, in the POM of the bundle that has that dependency. This is needed to maintain tracebility.
• Avoid declaring <bundle> and <feature> elements in the feature.xml file as much as possible, the karaf-maven-plugin should take care of that for you.

ZIP and Other Composed Artifacts

If your artifact is a zip or similar format that is formed through the composition of other artifacts and/or resources, then it's considered an assembly and it's module should be placed under the assemblies aggregator. Typically the maven-assembly-plugin has all the functionality needed for the creation of such artifacts. This plugin is available to you under if the project extends the Pentaho parent poms.

To trigger it's activation your assembly descriptor should be placed on /src/assembly/assembly.xml in your assembly module. This will activate the plugin and create the artifact with the instructions provided by the descriptor.

!!! WARNING !!!

The assembly plugin has a very annoying caveat when using it's dependencySet instruction with transitive dependencies. When it performs the resolution of the dependencies it does not process wildcard exclusions. This means that if somewhere down the dependency tree of a configured dependency and exclusion with * exists it will be ignored, and all transitives will be brought instead. The alternative, when dependencies are needed to compose the assembly, is to make use of the maven-dependency-plugin by running it's copy-dependencies goal in a preparation phase to copy the desired dependencies into a temporary location and the include those in your final package with the maven-assembly-plugin's fileSet instruction.

<plugin>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>add-libs</id>
      <phase>prepare-package</phase>
      <goals>
        <goal>copy-dependencies</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.build.directory}/lib</outputDirectory>
        <includeScope>runtime</includeScope>
      </configuration>
    </execution>
  </executions>
</plugin>