0
# Version Management
1

2
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.
3

4
## Core Version Classes
5

6
### ComparableVersion
7

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

10
```java { .api }
11
public class ComparableVersion implements Comparable<ComparableVersion> {
12
    public ComparableVersion(String version);
13
    public int compareTo(ComparableVersion other);
14
    public String getCanonical();
15
    public String toString();
16
    public boolean equals(Object other);
17
    public int hashCode();
18
    
19
    // CLI utility for testing version comparisons
20
    public static void main(String... args);
21
}
22
```
23

24
**Usage Examples**:
25

26
```java
27
// Basic version comparison
28
ComparableVersion v1 = new ComparableVersion("1.0");
29
ComparableVersion v2 = new ComparableVersion("1.0.1");
30
int result = v1.compareTo(v2); // Returns -1 (v1 < v2)
31

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

37
// Complex versions with qualifiers
38
ComparableVersion alpha = new ComparableVersion("1.0-alpha");
39
ComparableVersion beta = new ComparableVersion("1.0-beta");
40
ComparableVersion rc = new ComparableVersion("1.0-rc");
41
ComparableVersion final = new ComparableVersion("1.0");
42
// alpha < beta < rc < final
43

44
// Get canonical representation
45
String canonical = new ComparableVersion("1.0.0").getCanonical(); // "1"
46
```
47

48
### VersionRange
49

50
Constructs and manages version ranges for dependency specifications.
51

52
```java { .api }
53
public class VersionRange {
54
    // Factory methods
55
    public static VersionRange createFromVersionSpec(String spec) 
56
        throws InvalidVersionSpecificationException;
57
    public static VersionRange createFromVersion(String version);
58
    
59
    // Range operations
60
    public ArtifactVersion getRecommendedVersion();
61
    public List<Restriction> getRestrictions();
62
    public VersionRange restrict(VersionRange restriction) 
63
        throws OverConstrainedVersionException;
64
    
65
    // Version matching
66
    public boolean containsVersion(ArtifactVersion version);
67
    public ArtifactVersion matchVersion(List<ArtifactVersion> versions);
68
    
69
    // Artifact-specific operations
70
    public ArtifactVersion getSelectedVersion(Artifact artifact);
71
    public boolean isSelectedVersionKnown(Artifact artifact);
72
    
73
    // Standard methods
74
    public String toString();
75
    public boolean equals(Object other);
76
    public int hashCode();
77
}
78
```
79

80
**Usage Examples**:
81

82
```java
83
// Create version ranges
84
VersionRange range1 = VersionRange.createFromVersionSpec("[1.0,2.0)"); // 1.0 <= version < 2.0
85
VersionRange range2 = VersionRange.createFromVersionSpec("(,1.0]");    // version <= 1.0
86
VersionRange range3 = VersionRange.createFromVersionSpec("[1.0,)");    // version >= 1.0
87

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

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

95
// Find best matching version
96
List<ArtifactVersion> available = Arrays.asList(
97
    new DefaultArtifactVersion("0.9"),
98
    new DefaultArtifactVersion("1.2"),
99
    new DefaultArtifactVersion("1.8"),
100
    new DefaultArtifactVersion("2.1")
101
);
102
ArtifactVersion best = range1.matchVersion(available); // Returns "1.8"
103

104
// Combine ranges (intersection)
105
VersionRange combined = range1.restrict(range3); // [1.0,2.0)
106
```
107

108
### ArtifactVersion Interface
109

110
Describes artifact version components for detailed version analysis.
111

112
```java { .api }
113
public interface ArtifactVersion extends Comparable<ArtifactVersion> {
114
    int getMajorVersion();
115
    int getMinorVersion();
116
    int getIncrementalVersion();
117
    int getBuildNumber();
118
    String getQualifier();
119
    void parseVersion(String version);
120
    int compareTo(ArtifactVersion other);
121
    String toString();
122
}
123
```
124

125
### DefaultArtifactVersion
126

127
Default implementation of artifact versioning with component parsing.
128

129
```java { .api }
130
public class DefaultArtifactVersion implements ArtifactVersion {
131
    public DefaultArtifactVersion(String version);
132
    
133
    public int getMajorVersion();
134
    public int getMinorVersion(); 
135
    public int getIncrementalVersion();
136
    public int getBuildNumber();
137
    public String getQualifier();
138
    public void parseVersion(String version);
139
    public int compareTo(ArtifactVersion other);
140
    public String toString();
141
    public boolean equals(Object other);
142
    public int hashCode();
143
}
144
```
145

146
**Usage Examples**:
147

148
```java
149
// Parse version components
150
DefaultArtifactVersion version = new DefaultArtifactVersion("1.2.3-beta-4");
151
int major = version.getMajorVersion();        // 1
152
int minor = version.getMinorVersion();        // 2  
153
int incremental = version.getIncrementalVersion(); // 3
154
int build = version.getBuildNumber();         // 4
155
String qualifier = version.getQualifier();   // "beta"
156

157
// Compare versions
158
DefaultArtifactVersion v1 = new DefaultArtifactVersion("1.0.0");
159
DefaultArtifactVersion v2 = new DefaultArtifactVersion("1.0.1");
160
int comparison = v1.compareTo(v2); // Returns -1
161
```
162

163
### Restriction
164

165
Describes version range restrictions with bounds and inclusivity.
166

167
```java { .api }
168
public class Restriction {
169
    public static final Restriction EVERYTHING;
170
    
171
    public ArtifactVersion getLowerBound();
172
    public ArtifactVersion getUpperBound();
173
    public boolean isLowerBoundInclusive();
174
    public boolean isUpperBoundInclusive();
175
    public boolean containsVersion(ArtifactVersion version);
176
    public String toString();
177
    public boolean equals(Object other);
178
    public int hashCode();
179
}
180
```
181

182
**Usage Examples**:
183

184
```java
185
// Get restrictions from version range
186
VersionRange range = VersionRange.createFromVersionSpec("[1.0,2.0)");
187
List<Restriction> restrictions = range.getRestrictions();
188

189
for (Restriction restriction : restrictions) {
190
    ArtifactVersion lower = restriction.getLowerBound();     // 1.0
191
    ArtifactVersion upper = restriction.getUpperBound();     // 2.0
192
    boolean lowerInclusive = restriction.isLowerBoundInclusive(); // true
193
    boolean upperInclusive = restriction.isUpperBoundInclusive(); // false
194
    
195
    // Test if version fits restriction
196
    boolean fits = restriction.containsVersion(new DefaultArtifactVersion("1.5")); // true
197
}
198

199
// Unrestricted range
200
Restriction everything = Restriction.EVERYTHING;
201
```
202

203
## Exception Classes
204

205
### InvalidVersionSpecificationException
206

207
Thrown when version specification string cannot be parsed.
208

209
```java { .api }
210
public class InvalidVersionSpecificationException extends Exception {
211
    public InvalidVersionSpecificationException(String message);
212
    public InvalidVersionSpecificationException(String message, Throwable cause);
213
}
214
```
215

216
**Common Causes**:
217
- Invalid range syntax: `"[1.0,2.0"` (missing closing bracket)
218
- Malformed version numbers: `"1..0"`
219
- Invalid range bounds: `"[2.0,1.0]"` (lower > upper)
220

221
### OverConstrainedVersionException
222

223
Thrown when version ranges cannot be satisfied or are contradictory.
224

225
```java { .api }
226
public class OverConstrainedVersionException extends ArtifactResolutionException {
227
    public OverConstrainedVersionException(String message, Artifact artifact);
228
    public OverConstrainedVersionException(String message, Artifact artifact, 
229
                                         List<ArtifactRepository> remoteRepositories);
230
}
231
```
232

233
**Common Scenarios**:
234
- Conflicting version ranges: `[1.0,1.5]` intersected with `[2.0,3.0]`
235
- No available versions satisfy the range constraints
236
- Circular dependency with incompatible version requirements
237

238
## Version Range Syntax
239

240
Maven supports several version range syntaxes:
241

242
| Specification | Meaning |
243
|---------------|---------|
244
| `1.0` | Recommended version (soft requirement) |
245
| `[1.0]` | Exactly version 1.0 |
246
| `[1.0,2.0)` | 1.0 <= version < 2.0 |
247
| `[1.0,2.0]` | 1.0 <= version <= 2.0 |
248
| `(,1.0]` | version <= 1.0 |
249
| `[1.2,)` | version >= 1.2 |
250
| `(,1.0],[1.2,)` | version <= 1.0 or version >= 1.2 |
251
252
**Bracket Meanings**:
253
- `[` and `]` indicate inclusive bounds
254
- `(` and `)` indicate exclusive bounds
255

256
## Version Comparison Rules
257

258
Maven version comparison follows these rules:
259

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

266
## CLI Usage
267

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

270
```bash
271
java -cp maven-artifact-3.9.11.jar org.apache.maven.artifact.versioning.ComparableVersion 1.0 1.0.1
272
# Output: Display result: 1.0 < 1.0.1
273
```
274

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