Manifest spec/impl vs pom's version

Question

Well,

Package version numbers are present to identify differences between the specification and the implementation, i.e. bugs.

http://docs.oracle.com/javase/7/docs/technotes/guides/versioning/spec/versioning2.html

Assuming a vendor has a spec- and a impl- version offered.

Questions:

• Can a Maven spec-version be released twice when the impl is different?
• Why is no support for a optional spec-version in Maven?
• Does that mean i should use Spec-versions in Maven to keep beeing state of the art?

Answer 1

Maven and Java- Spec/Impl versions are slightly different concepts. They can be made to work with each other, however, it takes some effort.

Maven's multi-module approach encourages splitting modules into api (or spec) and implementation modules. So, to use the java versions, you would have to:

1. split your module into two modules, e.g. my-module-api and my-module-impl
2. define one or more properties inside your impl modules, pointing to the correct spec coordinates (version, and possibly groupId and artifactId as well)
3. have your manifest file either filtered or configuring the archiver to create the entries
4. (optionally) creating a shade artifact combining api and implementation (this somewhat negates the advantages of splitting your modules, however)

Look at the following example (I have ommited some best practices such as dependencyManagement for brevity's sake:

Specification Module:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.blackbuild.maven.demo.specimpl</groupId>
  <artifactId>module-spec</artifactId>
  <version>1.0</version>

  <name>Module Demo Specification</name>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-jar-plugin</artifactId>
          <version>2.4</version>
          <configuration>
            <archive>
              <manifest>
                <!-- This is an API project, use only specification entries -->
                <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
              </manifest>
            </archive>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

Specification Manifest:

Manifest-Version: 1.0
Built-By: xxx
Build-Jdk: 1.6.0_27
Specification-Title: Module Demo Specification
Created-By: Apache Maven 3.0.5
Specification-Version: 1.0
Archiver-Version: Plexus Archiver

Implementation Module

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.blackbuild.maven.demo.specimpl</groupId>
  <artifactId>module-impl</artifactId>
  <version>1.5-SNAPSHOT</version>

  <name>Module Demo Implementation</name>

  <properties>
    <!-- Define specification coordinates -->
    <spec-title>Module Demo Specification</spec-title>
    <spec-vendor>Spec Provider</spec-vendor>
    <spec-version>1.0</spec-version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.blackbuild.maven.demo.specimpl</groupId>
      <artifactId>module-spec</artifactId>
      <version>${spec-version}</version>
    </dependency>
  </dependencies>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-jar-plugin</artifactId>
          <version>2.4</version>
          <configuration>
            <archive>
              <manifest>
                <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
              </manifest>
              <manifestEntries>
                <Specification-Title>${spec-title}</Specification-Title>
                <Specification-Version>${spec-version}</Specification-Version>
                <Specification-Vendor>${spec-vendor}</Specification-Vendor>
              </manifestEntries>
            </archive>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

Implementation Manifest:

Manifest-Version: 1.0
Implementation-Title: Module Demo Implementation
Implementation-Version: 1.5-SNAPSHOT
Implementation-Vendor-Id: com.blackbuild.maven.demo.specimpl
Built-By: xxx
Build-Jdk: 1.6.0_27
Specification-Vendor: Spec Provider
Specification-Title: Module Demo Specification
Created-By: Apache Maven 3.0.5
Specification-Version: 1.0
Archiver-Version: Plexus Archiver

Consequences:

Of course, you have to release both modules individually.

Back to your questions:

• Can a Maven spec-version be released twice when the impl is different?

With this model, you can have different implementations for the same specification, as long as they have different coordinates themselves (different versions, usually).

• Why is no support for a optional spec-version in Maven?

Maven uses a single coordinate pre artifact, spec version is implemented by using dependencies. In normal workflow, you are either interested in spec version or in the implementation version, but rarely in both at the same time. You can assure that the implementation matches the specification by using dependencyManagement and enforcer rules, if necessary

• Does that mean i should use Spec-versions in Maven to keep beeing state of the art?

No, I think the api/impl model of Maven is more widely used.

One more thing...

In this model, there is no way to read the specification version from the implementation (without looking into the Manifest).

You could use a {spec-version}_{impl-version} versioning scheme to resolve this, for the above example, impl-version could be 1.5_1.0.0-SNAPSHOT, however this makes version numbers much harder to read.