org.eclipse.aether.util.version.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of maven-resolver-util Show documentation
A collection of utility classes to ease usage of the repository system.
There is a newer version: 2.0.5
// CHECKSTYLE_OFF: RegexpHeader
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
/**
 * Ready-to-use version scheme for parsing/comparing versions and utility classes.
 * 
 * Contains the "generic" scheme {@link org.eclipse.aether.util.version.GenericVersionScheme}
 * that serves the purpose of "factory" (and/or parser) for all corresponding elements (all those are package private).
 * 

 * On the other hand, the {@link org.eclipse.aether.util.version.UnionVersionRange} is universal implementation of
 * "unions" of various {@link org.eclipse.aether.version.VersionRange} instances.
 * 

 * Below is the Generic Version Spec described:
 * 

 * Version string is parsed into version according to these rules below:
 * 

 *     The version string is parsed into segments, from left to right.
 *     Segments are explicitly delimited by single {@code "." (dot)}, {@code "-" (hyphen)} or {@code "_" (underscore)} character.
 *     Segments are implicitly delimited by transition between digits and non-digits.
 *     Segments are classified as numeric, string, qualifiers (special case of string) and min/max.
 *     Numeric segments are sorted numerically, ascending.
 *     Non-numeric segments may be qualifiers (predefined) or strings (non-empty letter sequence). All of them are interpreted as being case-insensitive in terms of the ROOT locale.
 *     Qualifier segments (strings listed below) and their sort order (ascending) are:
 *         
 *             "alpha" (== "a" when immediately followed by number)
 *             "beta" (== "b" when immediately followed by number)
 *             "milestone" (== "m" when immediately followed by number)
 *             "rc" == "cr" (use of "cr" is discouraged)
 *             "snapshot"
 *             "ga" == "final" == "release"
 *             "sp"
 *         
 *     
 *     String segments are sorted lexicographically and case-insensitively per ROOT locale, ascending.
 *     There are two special segments, {@code "min"} and {@code "max"}, they represent absolute minimum and absolute maximum in comparisons. They can be used only as trailing segment.
 *     As last step, trailing "zero segments" are trimmed. Similarly, "zero segments" positioned before numeric and non-numeric transitions (either explicitly or implicitly delimited) are trimmed.
 *     When trimming, "zero segments" are qualifiers {@code "ga"}, {@code "final"}, {@code "release"} only if being last (right-most) segment, empty string and "0" always.
 *     In comparison of same kind segments, the given type of segment determines comparison rules.
 *     In comparison of different kind of segments, following applies: {@code max > numeric > string > qualifier > min}.
 *     Any version can be considered to have an infinite number of invisible trailing "zero segments", for the purposes of comparison (in other words, "1" == "1.0.0.0.0.0.0.0.0....")
 *     It is common that a version identifier starts with numeric segment (consider this "best practice").
 * 
 * 
 * Note: this version spec does not document (nor cover) many corner cases, that we believe are "atypical" or not
 * used commonly. None of these are enforced, but in future implementations they probably will be. Some known examples are:
 * 

 *     Using "min" or "max" special segments as non-trailing segment. This yields in "undefined" behaviour and should be avoided.
 *     Having non-number as first segment of version. Versions are expected (but not enforced) to start with numbers.
 * 
 *
 */
package org.eclipse.aether.util.version;