Creating JBoss SAR (Service ARchive) Artifacts

Background
Cookbook

Stand-alone SAR Project
SAR in a Multi-project Build, Included in an EAR

Related Work

Background

SAR is an acronym for "Service ARchive". SAR files are plain old Java JAR files that contain a JBoss service definition file (META-INF/jboss-service.xml) and (optionally) other resources needed by the service. By convention SAR files are named with a '.sar' extension.

Out of the box, Maven 2.x (at least as of version 2.0.7) does not include support creating SAR files, but there are a number of readily available plugins that provide this capability. Those that I am aware of include:

jboss-packaging-maven-plugin
maven-sar-plugin Note that despite the name, as of 2007-08-31, this plugin is not a core maven plugin
jboss-sar-maven-plugin As I understand it, this was the earlier work that lead to the above 'jboss-packaging-maven-plugin', and has since been superseded by it.

Cookbook

This section details how to create a SAR artifact using the 'jboss-packaging-maven-plugin'. There are two examples: the first example shows the case of creating a SAR in a simple (non-multi-project) maven-2.x project. The second example shows how to create a SAR artifact in a subproject of a larger multi-project, and then include the SAR in an EAR file created in a different subproject.

Stand-alone SAR Project

FIXME: document simple case

SAR in a Multi-project Build, Included in an EAR

The steps below below pertain only to use of the 'jboss-packaging-maven-plugin' plugin, currently available in the codehaus.org snapshots repository:

http://snapshots.repository.codehaus.org/org/codehaus/mojo/jboss-packaging-maven-plugin/

To configure use of the plugin, I added the following snippets to my top-level 'pom.xml' file:

  <project>
    <modules>
      <module>myproj-sar</module>
      <module>myproj-ear</module>
      ...
    </modules>
    ...
    <dependencyManagement>
      ...
       <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>myproj-sar</artifactId>
        <version>${project.version}</version>
        <type>sar</type>
      </dependency>
      ...
    </dependencyManagement>
    ...
    <build>
      ...
      <pluginManagement>
        <plugins>
          ...
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-ear-plugin</artifactId>
            <version>2.3.1</version>
          </plugin>
          <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>jboss-packaging-maven-plugin</artifactId>
            <version>2.0-SNAPSHOT</version>
          </plugin>
          ...
        </plugins>
      </pluginManagement>

      <plugins>
        ...
        <plugin>
          <groupId>org.codehaus.mojo</groupId>
          <artifactId>jboss-packaging-maven-plugin</artifactId>
          <!-- Enable 'jboss-sar', etc., as a recoginized maven packaging type -->
          <extensions>true</extensions>
        </plugin>
        ...
      </plugins>
      ...
    </build>
    ...
  </project>

In the 'pom.xml' of the subproject that produces the SAR file, I declared the packaging type as 'jboss-sar':

  <project>
    ...
    <artifactId>myproj-sar</artifactId>
    <packaging>jboss-sar</packaging>
    ...
  </project>

Note that the 'dependencyManagement' entry for the SAR subproject in the top-level 'pom.xml' file indicates type 'sar', but the packaging type declared by the SAR subproject itself is 'jboss-sar'. During the 'install' build phase, the SAR subproject will install the artifact with a '.sar' extension in the local maven repository.

In the 'pom.xml' file of the subproject that produces the EAR file, I have the following relevant snippets:

  <project>
    ...
    <dependencies>
      ...
      <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>myproj-sar</artifactId>
        <type>sar</type>
      </dependency>
      ...
    </dependencies>
    <build>
      <plugins>
        ...
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-ear-plugin</artifactId>
          <configuration>
            <!-- The version of the application.xml file to generate. Valid -->
            <!-- values include '1.3', '1.4', and '5'. -->
            <version>5</version>
            ...
            <modules>
              <!-- JBoss specific stuff -->
              <SarModule>
                <groupId>${project.groupId}</groupId>
                <artifactId>myproj-sar</artifactId>
              </SarModule>
              ...
            </modules>
            ...
          </configuration>
          <executions>
            <execution>
              <phase>package</phase>
              <goals>
                <goal>ear</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
  </project>

The things to note about this snippet are that the dependency type of the SAR module is 'sar' (not 'jboss-sar'), and the '<SarModule>' element of the 'maven-ear-plugin' configuration does not include a classifier.

Related Work

This wiki page was motivated by this discussion on the maven-users mailing list
The JBossService page on the JBoss wiki.