Exclude with smartics-jboss-modules

The smartics JBoss Modules Maven Plugin creates Modules for the JBoss Application Server. This includes the directory structure, the JAR artifacts and – of course – the module.xml.

This article provides information about exclusion mechanisms in modules descriptors used by the Maven plugin. It shows how to exclude Maven artifacts, skip module generation for already existing modules, and explains the meaning of the include/exclude tags.

Introduction

Everything starts with a Maven project object model (POM). The POM is either a bill of materials (BOM) or a regular project POM. Within this model a developer defines the dependencies of the project. These dependencies are used by the smartics JBoss Modules Maven Plugin to create a folder containing the modules for the transitive dependency chains.

Now let’s have a look at how to control the generation process to exclude artifacts from being turned into modules.

The Modules Descriptors

Since the JBoss module descriptors contain information that cannot be derived from a POM, the plugin defines modules descriptors files.

The Maven plugin traverses the dependencies and tries to match each dependency with a modules descriptor. If no matching modules descriptor has been found, a default module will be generated.

What is important to note:

1. Modules descriptors that do not match a Maven artifact, have no influence on the generation process. This implies that you may add any number of standard descriptors to the configuration to ease the pain of specifying the usual suspects. Please refer to External Modules Descriptors for the smartics-jboss-modules-maven-plugin for more information to this topic
2. Modules descriptors files contain information on modules and do not allow to exclude specific artifacts from the generation process. Global configurations for exclusions are found the the plugin’s configuration.

Let’s delve into the exclusion stuff …

Exclude an Artifact

If you have an artifact in the transitive closure of your project you want to exclude from the generation process, you have to specify the artifact in the dependencyExcludes within the plugin’s configuration section. Here is an example:

<plugin>
  <groupId>de.smartics.maven.plugin</groupId>
  <artifactId>smartics-jboss-modules-maven-plugin</artifactId>
  <version>0.2.0</version>
        ...
  <configuration>
    <dependencyExcludes>
      <exclude>
        <groupId>org.something</groupId>
        <artifactId>exclude-me</artifactId> 
      </exclude>
    </dependencyExcludes>
  </configuration>
</plugin>

This tells the generation process that the artifact, once encountered, will be dropped. The artifact will neither occur as a module in itself nor as a dependency of another module.

Here is an example configuration as part of our integration tests.

Skip the Generation of a Module

If you want to include the dependency in the module.xml, but you do not want to create a module for a given artifact, you may use the skip directive.

<modules xmlns="http://smartics.de/ns/jboss-modules-descriptor/1">
  <module name="org.something.exclude-me">
    <directives>
      <skip>true</skip>
    </directives>
    ...
  </module>
  ...
</modules>

This approach is useful if you want to depend on modules generated elsewhere. Either by other projects or the JBoss server itself.

Here is a modules.xml as part of our integration tests, that may serve as an example.

Exlusions

There are a couple of locations within the modules descriptor where you encounter an exclude tag. The following sections help you to distinguish them since they have mostly nothing to do with the exclusion of an artifact from the module generation process.

Exclude from Module Resources

Everything you match within the match element within the module descriptor is added as a resource to this module. Often there is a one-to-one relationship between the module and a resource, but this is not necessarily so. Here is the outline of the descriptor:

<modules xmlns="http://smartics.de/ns/jboss-modules-descriptor/1">
  <module name="org.something.my-module">
    ...
    <match>
      <includes>
        <include>
          <groupId></groupId>
          <artifactId></artifactId>
        </include>
        ...
        <include>
          <groupId></groupId>
          <artifactId></artifactId>
        </include>
      </includes>
      <excludes>
        <exclude>
          <groupId></groupId>
          <artifactId></artifactId>
        </exclude>
        ...
        <exclude>
          <groupId></groupId>
          <artifactId></artifactId>
        </exclude>
      </excludes>
    </match>
    ...
  </module>
  ...
</modules>

The exclude elements specify artifacts that are not to be added to the module as resources, although they match the includes. This allows to group a number of artifacts within one module. For each matching artifact no additional module will be generated.

Exclude from Applying Information to Dependency

We already mentioned that not all information of a JBoss module descriptor can be derived from a POM. The apply-to-dependencies allows to match modules (not artifacts as in the previous match element!) by their names and apply additional dependency information.

<modules xmlns="http://smartics.de/ns/jboss-modules-descriptor/1">
  <module name="org.something.my-module">
    ...
    <apply-to-dependencies>
      <dependencies>
        <match>
          <includes>
            <include></include>
            ...
            <include></include>
          </includes>
 
          <excludes>
            <exclude></exclude>
            ...
            <exclude></exclude>
          </excludes>
        </match>
        <apply>
          ... 
          <!-- 
            Add here information to be applied to 
            dependencies in the generated 
            module.xml 
            -->
         ...
        </apply>
      </dependencies>
      ...
    </apply-to-dependencies>
  </module>
  ...
</modules>

The exclude elements in the match section exclude the modules from having the information given in the apply element applied. It does not mean that the specified module is excluded from the dependency list of from the module generation.

There are examples as part of our integration tests that show you complete configurations.

  <apply>
    <slot></slot>
    <export></export>
    <services></services>
    <optional></optional>
    <imports>
      <include path="" />
      <include-set>
        <path name="" />
          ...
      </include-set>
      <exclude-set>
        <path name="org/jboss/example/tests2" />
          ...
      </exclude-set>
    </imports>
    <exports>
      <exclude path="" />
      <include-set>
        <path name="" />
          ...
      </include-set>
      <exclude-set>
        <path name="org/jboss/example/tests" />
        ...
      </exclude-set>
    </exports>
  </apply>

Exclude a Dependency?

There is currently (version 0.2.0) no way to simply drop an artifact dependency from being translated to the list of module dependencies.

As shown above:

1. you may use the exclusion of the artifact from the generation process. This will neither add a module for this artifact nor add the artifact as a dependency of any of the generated modules.
2. or, if you want the dependency, but not the module generated, use the skip directive.

If you have a use case that matches none of these approaches, please let us know!

Conclusion

We have summarized the semantics of the exclusion elements found in the smartics’ modules descriptor.

1. dependencyExcludes in the POM.
2. skip directive in a modules descriptor
3. exclusion elements in a modules descriptor

Hopefully this helps you to get fine grained control over your JBoss modules generation process.

For more information please refer to

• The jboss-modules articles in this blog.
• or to the smartics JBoss Modules Maven Plugin’s website.