CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-apache-maven--maven-artifact

Maven Artifact API provides core interfaces and classes for representing and working with Maven artifacts, including version handling, repository interactions, and metadata management

—

Pending
Overview
Eval results
Files

versioning.mddocs/

Version Management

Maven's version management system provides sophisticated capabilities for parsing, comparing, and working with software version numbers. It supports Maven's versioning conventions including snapshot versions, qualifier handling, and version range specifications.

Core Version Classes

ComparableVersion

Generic version comparison implementation that handles Maven's complex version semantics.

public class ComparableVersion implements Comparable<ComparableVersion> {
    public ComparableVersion(String version);
    public int compareTo(ComparableVersion other);
    public String getCanonical();
    public String toString();
    public boolean equals(Object other);
    public int hashCode();
    
    // CLI utility for testing version comparisons
    public static void main(String... args);
}

Usage Examples:

// Basic version comparison
ComparableVersion v1 = new ComparableVersion("1.0");
ComparableVersion v2 = new ComparableVersion("1.0.1");
int result = v1.compareTo(v2); // Returns -1 (v1 < v2)

// Snapshot versions
ComparableVersion snapshot = new ComparableVersion("1.0-SNAPSHOT");
ComparableVersion release = new ComparableVersion("1.0");
int comparison = snapshot.compareTo(release); // Returns -1 (snapshot < release)

// Complex versions with qualifiers
ComparableVersion alpha = new ComparableVersion("1.0-alpha");
ComparableVersion beta = new ComparableVersion("1.0-beta");
ComparableVersion rc = new ComparableVersion("1.0-rc");
ComparableVersion final = new ComparableVersion("1.0");
// alpha < beta < rc < final

// Get canonical representation
String canonical = new ComparableVersion("1.0.0").getCanonical(); // "1"

VersionRange

Constructs and manages version ranges for dependency specifications.

public class VersionRange {
    // Factory methods
    public static VersionRange createFromVersionSpec(String spec) 
        throws InvalidVersionSpecificationException;
    public static VersionRange createFromVersion(String version);
    
    // Range operations
    public ArtifactVersion getRecommendedVersion();
    public List<Restriction> getRestrictions();
    public VersionRange restrict(VersionRange restriction) 
        throws OverConstrainedVersionException;
    
    // Version matching
    public boolean containsVersion(ArtifactVersion version);
    public ArtifactVersion matchVersion(List<ArtifactVersion> versions);
    
    // Artifact-specific operations
    public ArtifactVersion getSelectedVersion(Artifact artifact);
    public boolean isSelectedVersionKnown(Artifact artifact);
    
    // Standard methods
    public String toString();
    public boolean equals(Object other);
    public int hashCode();
}

Usage Examples:

// Create version ranges
VersionRange range1 = VersionRange.createFromVersionSpec("[1.0,2.0)"); // 1.0 <= version < 2.0
VersionRange range2 = VersionRange.createFromVersionSpec("(,1.0]");    // version <= 1.0
VersionRange range3 = VersionRange.createFromVersionSpec("[1.0,)");    // version >= 1.0

// Single version
VersionRange exact = VersionRange.createFromVersion("1.0.0");

// Check if version matches range
boolean matches = range1.containsVersion(new DefaultArtifactVersion("1.5")); // true
boolean matches2 = range1.containsVersion(new DefaultArtifactVersion("2.0")); // false

// Find best matching version
List<ArtifactVersion> available = Arrays.asList(
    new DefaultArtifactVersion("0.9"),
    new DefaultArtifactVersion("1.2"),
    new DefaultArtifactVersion("1.8"),
    new DefaultArtifactVersion("2.1")
);
ArtifactVersion best = range1.matchVersion(available); // Returns "1.8"

// Combine ranges (intersection)
VersionRange combined = range1.restrict(range3); // [1.0,2.0)

ArtifactVersion Interface

Describes artifact version components for detailed version analysis.

public interface ArtifactVersion extends Comparable<ArtifactVersion> {
    int getMajorVersion();
    int getMinorVersion();
    int getIncrementalVersion();
    int getBuildNumber();
    String getQualifier();
    void parseVersion(String version);
    int compareTo(ArtifactVersion other);
    String toString();
}

DefaultArtifactVersion

Default implementation of artifact versioning with component parsing.

public class DefaultArtifactVersion implements ArtifactVersion {
    public DefaultArtifactVersion(String version);
    
    public int getMajorVersion();
    public int getMinorVersion(); 
    public int getIncrementalVersion();
    public int getBuildNumber();
    public String getQualifier();
    public void parseVersion(String version);
    public int compareTo(ArtifactVersion other);
    public String toString();
    public boolean equals(Object other);
    public int hashCode();
}

Usage Examples:

// Parse version components
DefaultArtifactVersion version = new DefaultArtifactVersion("1.2.3-beta-4");
int major = version.getMajorVersion();        // 1
int minor = version.getMinorVersion();        // 2  
int incremental = version.getIncrementalVersion(); // 3
int build = version.getBuildNumber();         // 4
String qualifier = version.getQualifier();   // "beta"

// Compare versions
DefaultArtifactVersion v1 = new DefaultArtifactVersion("1.0.0");
DefaultArtifactVersion v2 = new DefaultArtifactVersion("1.0.1");
int comparison = v1.compareTo(v2); // Returns -1

Restriction

Describes version range restrictions with bounds and inclusivity.

public class Restriction {
    public static final Restriction EVERYTHING;
    
    public ArtifactVersion getLowerBound();
    public ArtifactVersion getUpperBound();
    public boolean isLowerBoundInclusive();
    public boolean isUpperBoundInclusive();
    public boolean containsVersion(ArtifactVersion version);
    public String toString();
    public boolean equals(Object other);
    public int hashCode();
}

Usage Examples:

// Get restrictions from version range
VersionRange range = VersionRange.createFromVersionSpec("[1.0,2.0)");
List<Restriction> restrictions = range.getRestrictions();

for (Restriction restriction : restrictions) {
    ArtifactVersion lower = restriction.getLowerBound();     // 1.0
    ArtifactVersion upper = restriction.getUpperBound();     // 2.0
    boolean lowerInclusive = restriction.isLowerBoundInclusive(); // true
    boolean upperInclusive = restriction.isUpperBoundInclusive(); // false
    
    // Test if version fits restriction
    boolean fits = restriction.containsVersion(new DefaultArtifactVersion("1.5")); // true
}

// Unrestricted range
Restriction everything = Restriction.EVERYTHING;

Exception Classes

InvalidVersionSpecificationException

Thrown when version specification string cannot be parsed.

public class InvalidVersionSpecificationException extends Exception {
    public InvalidVersionSpecificationException(String message);
    public InvalidVersionSpecificationException(String message, Throwable cause);
}

Common Causes:

  • Invalid range syntax: "[1.0,2.0" (missing closing bracket)
  • Malformed version numbers: "1..0"
  • Invalid range bounds: "[2.0,1.0]" (lower > upper)

OverConstrainedVersionException

Thrown when version ranges cannot be satisfied or are contradictory.

public class OverConstrainedVersionException extends ArtifactResolutionException {
    public OverConstrainedVersionException(String message, Artifact artifact);
    public OverConstrainedVersionException(String message, Artifact artifact, 
                                         List<ArtifactRepository> remoteRepositories);
}

Common Scenarios:

  • Conflicting version ranges: [1.0,1.5] intersected with [2.0,3.0]
  • No available versions satisfy the range constraints
  • Circular dependency with incompatible version requirements

Version Range Syntax

Maven supports several version range syntaxes:

SpecificationMeaning
1.0Recommended version (soft requirement)
[1.0]Exactly version 1.0
[1.0,2.0)1.0 <= version < 2.0
[1.0,2.0]1.0 <= version <= 2.0
(,1.0]version <= 1.0
[1.2,)version >= 1.2
(,1.0],[1.2,)version <= 1.0 or version >= 1.2

Bracket Meanings:

  • [ and ] indicate inclusive bounds
  • ( and ) indicate exclusive bounds

Version Comparison Rules

Maven version comparison follows these rules:

  1. Numeric components: Compared numerically (1 < 2 < 10)
  2. Qualifiers: Alphabetically ordered with special cases:
    • alpha < beta < milestone < rc < snapshot < (no qualifier) < sp
  3. Snapshot versions: Always less than their release counterpart
  4. Missing components: Treated as zero (1.0 == 1.0.0)

CLI Usage

The ComparableVersion class includes a main method for command-line version comparison:

java -cp maven-artifact-3.9.11.jar org.apache.maven.artifact.versioning.ComparableVersion 1.0 1.0.1
# Output: Display result: 1.0 < 1.0.1

This is useful for testing version comparison behavior and debugging version ordering issues.

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-maven--maven-artifact

docs

index.md

repository.md

resolution.md

versioning.md

tile.json