This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • Project Dependency Trees schema

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The rationale for choosing XSLT as the transformation... and consequently forcing the Project Dependency Trees model to be expressed in XML is that XSLT is currently the only cross-platform transformation engine available across the JVM, Ruby, .NET, C/C++ native code and JavaScript runtimes.

TODO write the content and formalise the following example into a schema:

...

Artifact Dependency differentiation

The current POM provides a single scoped dependency tree that is then universally applied to all artifacts produced by the project. This does not align correctly with what the artifacts produced by a single project actually require.

To illustrate by example:

Consider a project that builds a Java Web application that can be run standalone or as part of an EAR. Under current best-practice we would advise separating the project into multiple modules:

  • A module to build the JAR file that contains the compiled code and corresponding resources
  • A module to build the WAR file for consumption as part of an EAR - this needs to be skinny as the common dependencies will be shared across all the modules within the EAR
  • A module to build the WAR file for standalone - this needs to be fat and is built from the skinny WAR by adding in the common dependencies

There are other ways to skin this cat, but what we really want to have is that there is a single project that produces:

  • A JAR of the compiled code - we may want to reuse this
  • A skinny WAR which exposes transitive dependencies of the common dependencies that are required to be present in the EAR
  • A fat WAR which does not expose any transitive dependencies - perhaps other than the servlet container and JVM level requirements
  • A test JAR that allows for re-use of the unit tests of the compiled code
  • An integration test JAR that allows for extending and running the WAR acceptance tests
  • A source JAR for the main JAR
  • A javadoc JAR for the main JAR
  • A source JAR for the test JAR
  • A javadoc JAR for the test JAR
  • A source JAR for the integration test JAR
  • A javadoc JAR for the integration test JAR

Each of these artifacts will have different effective dependencies, for example the test JAR will have a dependency on the main JAR and then a dependency on the test framework, etc.

The way the modelVersion 4.0.0 POM handled these different dependencies was via <scope> tags. The issue with scope tags is that the valid scopes become part of the model version and the information about which scopes apply to which artifacts has been lost to the build process by the time the artifacts is consumed by a consumer.

To solve this issue, the Project Dependency Trees will list the effective consumption required dependencies of each artifact produced by the project. 

NOTE the Project Dependency Trees will have no concept of scope. This may cause issues for artifact types where for example a different dependency is transitive during compilation compared with execution. The current thinking is that such situations will be exceedingly rare if they ever occur, and that as such, for least surprise, the consumer will have to configure their build tool to address this issue if it ever arises.

Non-atomic deployment

The primary driver of non-atomic deployment is the production of platform specific artifacts for the project.

 

 

 

 

<project modelVersion="..." groupId="..." artifactId="..." [platformId="..."] version="...">
    <information>
        <!-- container for descriptive information -->
        [<name>...</name>]
        [<description>...</description>]
        ...
    </information>
<license spdxId="..."/>
<license spdxId="..."/>
...
<license spdxId="..."/>
    <artifacts [platformId="..."]>
        <artifact type="..." [classifier="..."]>
            <information>
                <!-- optional element if need to override root level information for specific artifacts -->
            </information>
            <!-- 
              components are internal packaging constructs used by the packaging type but requiring more general validation
              e.g. for Java 9+ the ids could be the module ids if we wanted to validate that the module ids were unique in the
              effective tree.
            -->
            <component id="..."/>
            <component id="..."/>
            ...
            <component id="..."/>
            <!--
If the artifact has a different set of licenses from those defined at the project level, we define the licenses
of this artifact here. Otherwise we defer to the licenses defined at the top level of the project.
              licensing is a top level concern, and legitimately can vary per artifact. Let's not solve license compatibility, 
              rather leverage https://spdx.org/
            -->
            <license spdx:id="..."/>
            <license spdx:id="..."/>
            ...
            <license spdx:id="..."/>
            <!--
              provides is a marker that we have duplication of content. This could be because we are much like the many servlet-api jar
              files where there are many GAV's of the same javax.servlet:servlet-api:3.0 thus we could have the case where
 
              org.jboss.spec.javax.servlet:jboss-servlet-api_3.0_spec:jar:1.0.2.Final PROVIDES javax.servlet:servlet-api:3.0
              org.jboss.spec.javax.servlet:jboss-servlet-api_3.0_spec:jar:1.0.1.Final PROVIDES javax.servlet:servlet-api:3.0
              org.jboss.spec.javax.servlet:jboss-servlet-api_3.0_spec:jar:1.0.0.Final PROVIDES javax.servlet:servlet-api:3.0
              org.mortbay.jetty:servlet-api-3.0:jar:7.0.0pre2 PROVIDES javax.servlet:servlet-api:3.0
 
              similarly
 
              org.slf4j:log4j-over-slf4j:jar:1.7.21 PROVIDES log4j:log4j:[1.0,2)
 
              The consumer of the tree can then decide if/when/how to collapse redundant nodes as they see fit.
 
              TODO: decide optionality of version and range attributes
            -->
            <provides groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]>
                <!-- no elements here as we have "rebundled" hence implicitly promoted up one level-->
            </provides>
            <provides groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]/>
            ...
            <provides groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]/>
            <!--
              requires are the mandatory dependencies. This is effectively a recursive artifact where the GAV is not inherited and
              where we have discarded the information section. If you want those details, fetch that project's dependencies trees.
            -->
            <requires groupId="..." artifactId="..." [platformId="..."] version="..." range="..." type="..." [classifier="..."]>
                <component id="..."/>
                <license spdx:id="..."/>
                <provides groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]/>
                <requires groupId="..." artifactId="..." [platformId="..."] version="..." range="..." type="..." [classifier="..."]>
                    ...
                </requires>
                <supports groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]/>
            </requires>
            <requires groupId="..." artifactId="..." [platformId="..."] version="..." range="..." type="..." [classifier="..."]>
                ...
            </requires>
            ...
            <requires groupId="..." artifactId="..." [platformId="..."] version="..." range="..." type="..." [classifier="..."]>
                ...
            </requires>
            <!--
              supports are the optional dependencies. We list them here to aid in conflict resolution. We do not include a nested tree
              as a consumer would only pull them in if the consumer already has its own a requires for them, so we really only
              need to validate the range. 
 
              TODO: decide optionality of range attribute
              TODO: decide if we want a version attribute 
            -->
            <supports groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]/>
            <supports groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]/>
            <supports groupId="..." artifactId="..." [platformId="..."] version="..." [range="..."] type="..." [classifier="..."]/>
        </artifact>
        <artifact ...>
            ...
        </artifact>
        ...
        <artifact ...>
            ...
        </artifact>
    </artifacts>
<!-- if the project does not specify a platformId then we can include additional platform details that were part of the atomic deployment -->
<artifacts platformId="...">
...
</artifacts>
...
<artifacts platformId="...">
...
</artifacts>
</project>
Schema
Here is a draft XML schema:
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema" >
<xsd:simpleType name=”coordinate”>
<xsd:restriction base=”xsd:string”>
<!-- TODO add pattern for groupId/artifactId/platformId/version/type/classifier valid values -->
</xsd:restriction>
</xsd:simpleType>
<xs:element name="project">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;project&gt;</code> element is the root of the project
dependency trees.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="modelVersion" type="xs:string"/>
<xs:attribute name="groupId" type="coordinate"/>
<xs:attribute name="artifactId" type="coordinate"/>
<xs:attribute name="version" type="coordinate"/>
<xs:attribute name="platformId" type="coordinate" use="optional"/>
<xs:all>
<xs:element ref="information" minOccurs="0" maxOccurs="1"/>
<xs:element ref="license" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="artifacts" minOccurs="1" maxOccurs="unbounded"/>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="information">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;information&gt;</code> element is a container for
descriptive information about either all the artifacts in a project or
a specific artifact.</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:all>
<xs:element name="name" type="xs:string" maxOccurs="1"/>
<xs:element name="description" type="xs:string" maxOccurs="1"/>
<!-- TODO add additional elements -->
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="license" xmlns:spdx="http://spdx.org/rdf/terms#">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;license&gt;</code> element defines one of the licenses
under which the artifacts are made available. Where a license is
attached to the <code>&lt;project&gt;</code> element this defines the
default licenses for all artifacts in the project. Where a license is
attached to an <code>&lt;artifact&gt;</code> element this signifies
that the specific artifact is covered by the
<code>&lt;license&gt;</code> elements defined within that
<code>&lt;artifact&gt;</code> element. Licenses are identified using
the <a href="http://spdx.org">SPDX</a> identifiers</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="spdxId" type="xs:string"/>
</xs:complexType>
</xs:element>
<xs:element name="artifacts">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;artifacts&gt;</code> element is a container for
details of artifacts. When the <code>&lt;artifacts&gt;</code> attribute
is missing, then the artifacts listed are not platform specific.
The <code>&lt;artifacts&gt;</code> must be unique with respect to their
<code>&lt;platformId&gt;</code>, i.e. it cannot be repeated.
If the <code>&lt;project&gt;</code> element has a
<code>&lt;platformId&gt;</code> then there must be only one
<code>&lt;artifacts&gt;</code> element and it must have the matching
<code>&lt;platformId&gt;</code>.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="platformId" type="coordinate" use="optional"/>
<xs:sequence>
<xs:element ref="artifact" minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="artifact">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;artifact&gt;</code> element represents an artifact
associated with the project.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="type" type="coordinate"/>
<xs:attribute name="classifier" type="coordinate" use="optional"/>
<xs:all>
<xs:element ref="information" minOccurs="0" maxOccurs="1"/>
<xs:element ref="license" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="component" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="provides" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="requires" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="supports" minOccurs="0" maxOccurs="unbounded"/>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="component">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;component&gt;</code> element represents a type specific
component that is present within the artifact. For example a "jar"
artifact might list the Java 9+ modules that are included within
the "jar". Other file types can use the component according to the
conventions of that file type. The component information is intended
to assist build time tools in conflict detection when resolving
the composite dependency tree according to the build tools
dependency resolution strategy.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="id" type="xs:string"/>
</xs:complexType>
</xs:element>
<xs:element name="provides">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;provides&gt;</code> element represents a semantic
equivalence with another artifact. There are several ways the element
can be used.
<nl>
<li>
When an artifact directly includes the same content as another
project's artifacts, for example there are some "jar" files that
will embed other artifacts to produce a so-called "uber-jar".
</li>
<li>
When an artifact re-implements the API of another project's
artifact. For example: log4j-over-slf4j reimplements the log4j
API.
</li>
<li>
When a set of projects are co-operating to provide multiple
implementations of a "virtual" project artifact. For example:
slf4j-log4j, slf4j-jul, and logback could all be considered
as providing a slf4j-impl virtual project artifact. There would
be no actual project at the slf4j-impl coordinates, but
slf4j-api could declare a requirement on the "virtual" project
artifact in order to ensure that an implementation is available
to consumers of the API
</nl>
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="groupId" type="coordinate"/>
<xs:attribute name="artifactId" type="coordinate"/>
<xs:attribute name="platformId" type="coordinate" use="optional"/>
<xs:attribute name="version" type="coordinate"/>
<xs:attribute name="range" type="xs:string"/>
<xs:attribute name="type" type="coordinate"/>
<xs:attribute name="classifier" type="coordinate" use="optional"/>
</xs:complexType>
</xs:element>
<xs:element name="requires">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;requires&gt;</code> element represents a hard dependency
on another project's artifact. If the <code>&lt;version&gt;</code>
attribute is missing then this indicates that the dependency is
a virtual dependency, and there must be no child elements.
The <code>&lt;modelVersion&gt;</code> attribute must only be present
if the dependent project's <code>&lt;modelVersion&gt;</code> is newer
than the <code>&lt;modelVersion&gt;</code> specified on the root
<code>&lt;project&gt;</code> element. The presence of this element
indicates that the child information was the result of an XSLT
transformation of a newer <code>&lt;modelVersion&gt;</code> and
indicates that a build tool understanding the newer
<code>&lt;modelVersion&gt;</code> may want to fetch the dependencies
tree and process it directly in order to obtain the most correct
model of the dependency.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="groupId" type="coordinate"/>
<xs:attribute name="artifactId" type="coordinate"/>
<xs:attribute name="platformId" type="coordinate" use="optional"/>
<xs:attribute name="version" type="coordinate" use="optional"/>
<xs:attribute name="range" type="xs:string"/>
<xs:attribute name="type" type="coordinate"/>
<xs:attribute name="classifier" type="coordinate" use="optional"/>
<xs:attribute name="modelVersion" type="xs:string" use="optional"/>
<xs:all>
<xs:element ref="license" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="component" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="provides" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="requires" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="supports" minOccurs="0" maxOccurs="unbounded"/>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="supports">
<xs:annotation>
<xs:documentation source="version">5.0.0+</xs:documentation>
<xs:documentation source="description">
The <code>&lt;supports&gt;</code> element represents a soft dependency
on another project's artifact. This element is provided in order to
allow build time tools to perform conflict resolution when determining
the effective tree from multiple dependencies.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="groupId" type="coordinate"/>
<xs:attribute name="artifactId" type="coordinate"/>
<xs:attribute name="platformId" type="coordinate" use="optional"/>
<xs:attribute name="version" type="coordinate"/>
<xs:attribute name="range" type="xs:string"/>
<xs:attribute name="type" type="coordinate"/>
<xs:attribute name="classifier" type="coordinate" use="optional"/>
</xs:complexType>
</xs:element>
</xs:schema>