< prev index next >

src/java.base/share/classes/java/lang/Runtime.java

Print this page
rev 48062 : 8192833: JEP 322: Time-Based Release Versioning


 938      * @return  the {@link Version} of the Java Runtime Environment
 939      *
 940      * @since  9
 941      */
 942     public static Version version() {
 943         if (version == null) {
 944             version = new Version(VersionProps.versionNumbers(),
 945                     VersionProps.pre(), VersionProps.build(),
 946                     VersionProps.optional());
 947         }
 948         return version;
 949     }
 950 
 951     /**
 952      * A representation of a version string for an implementation of the
 953      * Java&nbsp;SE Platform.  A version string consists of a version number
 954      * optionally followed by pre-release and build information.
 955      *
 956      * <h2><a id="verNum">Version numbers</a></h2>
 957      *
 958      * <p> A <em>version number</em>, {@code $VNUM}, is a non-empty sequence
 959      * of elements separated by period characters (U+002E).  An element is
 960      * either zero, or an unsigned integer numeral without leading zeros.  The
 961      * final element in a version number must not be zero.  The format is:
 962      * </p>
 963      *
 964      * <blockquote><pre>
 965      *     [1-9][0-9]*((\.0)*\.[1-9][0-9]*)*
 966      * </pre></blockquote>
 967      *
 968      * <p> The sequence may be of arbitrary length but the first three
 969      * elements are assigned specific meanings, as follows:</p>
 970      *
 971      * <blockquote><pre>
 972      *     $MAJOR.$MINOR.$SECURITY
 973      * </pre></blockquote>
 974      *
 975      * <ul>
 976      *
 977      * <li><p> <a id="major">{@code $MAJOR}</a> --- The major version
 978      * number, incremented for a major release that contains significant new
 979      * features as specified in a new edition of the Java SE Platform
 980      * Specification, <em>e.g.</em>, <a
 981      * href="https://jcp.org/en/jsr/detail?id=337">JSR 337</a> for
 982      * Java SE 8.  Features may be removed in a major release, given
 983      * advance notice at least one major release ahead of time, and
 984      * incompatible changes may be made when justified. The {@code $MAJOR}
 985      * version number of JDK 8 is {@code 8}; the {@code $MAJOR} version
 986      * number of JDK 9 is {@code 9}.  When {@code $MAJOR} is incremented,
 987      * all subsequent elements are removed. </p></li>
 988      *
 989      * <li><p> <a id="minor">{@code $MINOR}</a> --- The minor version
 990      * number, incremented for a minor update release that may contain
 991      * compatible bug fixes, revisions to standard APIs mandated by a
 992      * <a href="https://jcp.org/en/procedures/jcp2#5.3">Maintenance Release</a>
 993      * of the relevant Platform Specification, and implementation features
 994      * outside the scope of that Specification such as new JDK-specific APIs,
 995      * additional service providers, new garbage collectors, and ports to new
 996      * hardware architectures. </p></li>
 997      *
 998      * <li><p> <a id="security">{@code $SECURITY}</a> --- The security
 999      * level, incremented for a security update release that contains critical
1000      * fixes including those necessary to improve security.  {@code $SECURITY}
1001      * is <strong>not</strong> reset when {@code $MINOR} is incremented.  A
1002      * higher value of {@code $SECURITY} for a given {@code $MAJOR} value,
1003      * therefore, always indicates a more secure release, regardless of the
1004      * value of {@code $MINOR}. </p></li>
1005      *
1006      * </ul>
1007      *
1008      * <p> The fourth and later elements of a version number are free for use
1009      * by downstream consumers of this code base.  Such a consumer may,
1010      * <em>e.g.</em>, use the fourth element to identify patch releases which
1011      * contain a small number of critical non-security fixes in addition to
1012      * the security fixes in the corresponding security release. </p>
1013      *
1014      * <p> The version number does not include trailing zero elements;
1015      * <em>i.e.</em>, {@code $SECURITY} is omitted if it has the value zero,
1016      * and {@code $MINOR} is omitted if both {@code $MINOR} and {@code
1017      * $SECURITY} have the value zero. </p>
1018      *
1019      * <p> The sequence of numerals in a version number is compared to another
1020      * such sequence in numerical, pointwise fashion; <em>e.g.</em>, {@code
1021      * 9.9.1} is less than {@code 9.10.3}. If one sequence is shorter than
1022      * another then the missing elements of the shorter sequence are
1023      * considered to be less than the corresponding elements of the longer
1024      * sequence; <em>e.g.</em>, {@code 9.1.2} is less than {@code 9.1.2.1}.
1025      * </p>
1026      *
1027      * <h2><a id="verStr">Version strings</a></h2>
1028      *
1029      * <p> A <em>version string</em>, {@code $VSTR}, consists of a version
1030      * number {@code $VNUM}, as described above, optionally followed by
1031      * pre-release and build information, in one of the following formats:
1032      * </p>
1033      *
1034      * <blockquote><pre>
1035      *     $VNUM(-$PRE)?\+$BUILD(-$OPT)?
1036      *     $VNUM-$PRE(-$OPT)?
1037      *     $VNUM(+-$OPT)?
1038      * </pre></blockquote>
1039      *
1040      * <p> where: </p>
1041      *
1042      * <ul>
1043      *
1044      * <li><p> <a id="pre">{@code $PRE}</a>, matching {@code ([a-zA-Z0-9]+)}
1045      * --- A pre-release identifier.  Typically {@code ea}, for a
1046      * potentially unstable early-access release under active development,
1047      * or {@code internal}, for an internal developer build. </p></li>
1048      *
1049      * <li><p> <a id="build">{@code $BUILD}</a>, matching {@code
1050      * (0|[1-9][0-9]*)} --- The build number, incremented for each promoted
1051      * build.  {@code $BUILD} is reset to {@code 1} when any portion of {@code
1052      * $VNUM} is incremented. </p></li>
1053      *
1054      * <li><p> <a id="opt">{@code $OPT}</a>, matching {@code
1055      * ([-a-zA-Z0-9.]+)} --- Additional build information, if desired.  In
1056      * the case of an {@code internal} build this will often contain the date
1057      * and time of the build. </p></li>
1058      *
1059      * </ul>
1060      *
1061      * <p> A version string {@code 10-ea} matches {@code $VNUM = "10"} and
1062      * {@code $PRE = "ea"}.  The version string {@code 10+-ea} matches
1063      * {@code $VNUM = "10"} and {@code $OPT = "ea"}. </p>
1064      *
1065      * <p> When comparing two version strings, the value of {@code $OPT}, if
1066      * present, may or may not be significant depending on the chosen
1067      * comparison method.  The comparison methods {@link #compareTo(Version)
1068      * compareTo()} and {@link #compareToIgnoreOptional(Version)
1069      * compareToIgnoreOptional()} should be used consistently with the
1070      * corresponding methods {@link #equals(Object) equals()} and {@link
1071      * #equalsIgnoreOptional(Object) equalsIgnoreOptional()}.  </p>
1072      *
1073      * <p> A <em>short version string</em>, {@code $SVSTR}, often useful in
1074      * less formal contexts, is a version number optionally followed by a
1075      * pre-release identifier:</p>
1076      *
1077      * <blockquote><pre>


1121          *         A string to interpret as a version
1122          *
1123          * @throws  IllegalArgumentException
1124          *          If the given string cannot be interpreted as a valid
1125          *          version
1126          *
1127          * @throws  NullPointerException
1128          *          If the given string is {@code null}
1129          *
1130          * @throws  NumberFormatException
1131          *          If an element of the version number or the build number
1132          *          cannot be represented as an {@link Integer}
1133          *
1134          * @return  The Version of the given string
1135          */
1136         public static Version parse(String s) {
1137             if (s == null)
1138                 throw new NullPointerException();
1139 
1140             // Shortcut to avoid initializing VersionPattern when creating
1141             // major version constants during startup
1142             if (isSimpleNumber(s)) {
1143                 return new Version(List.of(Integer.parseInt(s)),
1144                         Optional.empty(), Optional.empty(), Optional.empty());
1145             }
1146             Matcher m = VersionPattern.VSTR_PATTERN.matcher(s);
1147             if (!m.matches())
1148                 throw new IllegalArgumentException("Invalid version string: '"
1149                                                    + s + "'");
1150 
1151             // $VNUM is a dot-separated list of integers of arbitrary length
1152             String[] split = m.group(VersionPattern.VNUM_GROUP).split("\\.");
1153             Integer[] version = new Integer[split.length];
1154             for (int i = 0; i < split.length; i++) {
1155                 version[i] = Integer.parseInt(split[i]);
1156             }
1157 
1158             Optional<String> pre = Optional.ofNullable(
1159                     m.group(VersionPattern.PRE_GROUP));
1160 
1161             String b = m.group(VersionPattern.BUILD_GROUP);


1178                 } else {
1179                     throw new IllegalArgumentException("'+' found with neither"
1180                         + " build or optional components: '" + s + "'");
1181                 }
1182             }
1183             return new Version(List.of(version), pre, build, optional);
1184         }
1185 
1186         private static boolean isSimpleNumber(String s) {
1187             for (int i = 0; i < s.length(); i++) {
1188                 char c = s.charAt(i);
1189                 char lowerBound = (i > 0) ? '0' : '1';
1190                 if (c < lowerBound || c > '9') {
1191                     return false;
1192                 }
1193             }
1194             return true;
1195         }
1196 
1197         /**
1198          * Returns the <a href="#major">major</a> version number.

1199          *
1200          * @return  The major version number
1201          */
1202         public int major() {
1203             return version.get(0);
1204         }
1205 
1206         /**
1207          * Returns the <a href="#minor">minor</a> version number or zero if it
1208          * was not set.
1209          *
1210          * @return  The minor version number or zero if it was not set
1211          */
1212         public int minor() {
1213             return (version.size() > 1 ? version.get(1) : 0);
1214         }
1215 
1216         /**
1217          * Returns the <a href="#security">security</a> version number or zero
1218          * if it was not set.
1219          *
1220          * @return  The security version number or zero if it was not set
1221          */
1222         public int security() {
1223             return (version.size() > 2 ? version.get(2) : 0);
1224         }
1225 
1226         /**
1227          * Returns an unmodifiable {@link java.util.List List} of the
1228          * integer numerals contained in the <a href="#verNum">version
1229          * number</a>.  The {@code List} always contains at least one
1230          * element corresponding to the <a href="#major">major version
1231          * number</a>.






























































1232          *
1233          * @return  An unmodifiable list of the integer numerals
1234          *          contained in the version number
1235          */
1236         public List<Integer> version() {
1237             return version;
1238         }
1239 
1240         /**
1241          * Returns the optional <a href="#pre">pre-release</a> information.
1242          *
1243          * @return  The optional pre-release information as a String
1244          */
1245         public Optional<String> pre() {
1246             return pre;
1247         }
1248 
1249         /**
1250          * Returns the <a href="#build">build number</a>.
1251          *
1252          * @return  The optional build number.
1253          */
1254         public Optional<Integer> build() {




 938      * @return  the {@link Version} of the Java Runtime Environment
 939      *
 940      * @since  9
 941      */
 942     public static Version version() {
 943         if (version == null) {
 944             version = new Version(VersionProps.versionNumbers(),
 945                     VersionProps.pre(), VersionProps.build(),
 946                     VersionProps.optional());
 947         }
 948         return version;
 949     }
 950 
 951     /**
 952      * A representation of a version string for an implementation of the
 953      * Java&nbsp;SE Platform.  A version string consists of a version number
 954      * optionally followed by pre-release and build information.
 955      *
 956      * <h2><a id="verNum">Version numbers</a></h2>
 957      *
 958      * <p> A <em>version number</em>, {@code $VNUM}, is a non-empty sequence of
 959      * elements separated by period characters (U+002E).  An element is either
 960      * zero, or an unsigned integer numeral without leading zeros.  The final
 961      * element in a version number must not be zero.  When an element is
 962      * incremented, all subsequent elements are removed.  The format is: </p>
 963      *
 964      * <blockquote><pre>
 965      * [1-9][0-9]*((\.0)*\.[1-9][0-9]*)*
 966      * </pre></blockquote>
 967      *
 968      * <p> The sequence may be of arbitrary length but the first four elements
 969      * are assigned specific meanings, as follows:</p>
 970      *
 971      * <blockquote><pre>
 972      * $FEATURE.$INTERIM.$UPDATE.$PATCH
 973      * </pre></blockquote>
 974      *
 975      * <ul>
 976      *
 977      * <li><p> <a id="FEATURE">{@code $FEATURE}</a> — The
 978      * feature-release counter, incremented for every feature release
 979      * regardless of release content.  Features may be added in a feature
 980      * release; they may also be removed, if advance notice was given at least
 981      * one feature release ahead of time.  Incompatible changes may be made
 982      * when justified. </p></li>
 983      *
 984      * <li><p> <a id="INTERIM">{@code $INTERIM}</a> — The
 985      * interim-release counter, incremented for non-feature releases that
 986      * contain compatible bug fixes and enhancements but no incompatible
 987      * changes, no feature removals, and no changes to standard APIs.
 988      * </p></li>
 989      *
 990      * <li><p> <a id="UPDATE">{@code $UPDATE}</a> — The update-release
 991      * counter, incremented for compatible update releases that fix security
 992      * issues, regressions, and bugs in newer features. </p></li>
 993      *
 994      * <li><p> <a id="PATCH">{@code $PATCH}</a> — The emergency
 995      * patch-release counter, incremented only when it's necessary to produce
 996      * an emergency release to fix a critical issue. </p></li>








 997      *
 998      * </ul> 
 999      *
1000      * <p> The fifth and later elements of a version number are free for use by
1001      * platform implementors, to identify implementor-specific patch
1002      * releases. </p>
1003      *
1004      * <p> A version number never has trailing zero elements.  If an element
1005      * and all those that follow it logically have the value zero then all of
1006      * them are omitted. </p>



1007      *
1008      * <p> The sequence of numerals in a version number is compared to another
1009      * such sequence in numerical, pointwise fashion; <em>e.g.</em>, {@code
1010      * 10.0.4} is less than {@code 10.1.2}.  If one sequence is shorter than
1011      * another then the missing elements of the shorter sequence are considered
1012      * to be less than the corresponding elements of the longer sequence;
1013      * <em>e.g.</em>, {@code 10.0.2} is less than {@code 10.0.2.1}. </p>

1014      *
1015      * <h2><a id="verStr">Version strings</a></h2>
1016      *
1017      * <p> A <em>version string</em>, {@code $VSTR}, is a version number {@code
1018      * $VNUM}, as described above, optionally followed by pre-release and build
1019      * information, in one of the following formats: </p>

1020      *
1021      * <blockquote><pre>
1022      *     $VNUM(-$PRE)?\+$BUILD(-$OPT)?
1023      *     $VNUM-$PRE(-$OPT)?
1024      *     $VNUM(+-$OPT)?
1025      * </pre></blockquote>
1026      *
1027      * <p> where: </p>
1028      *
1029      * <ul>
1030      *
1031      * <li><p> <a id="pre">{@code $PRE}</a>, matching {@code ([a-zA-Z0-9]+)}
1032      * — A pre-release identifier.  Typically {@code ea}, for a
1033      * potentially unstable early-access release under active development, or
1034      * {@code internal}, for an internal developer build. </p></li>
1035      *
1036      * <li><p> <a id="build">{@code $BUILD}</a>, matching {@code
1037      * (0|[1-9][0-9]*)} — The build number, incremented for each promoted
1038      * build.  {@code $BUILD} is reset to {@code 1} when any portion of {@code
1039      * $VNUM} is incremented. </p></li>
1040      *
1041      * <li><p> <a id="opt">{@code $OPT}</a>, matching {@code ([-a-zA-Z0-9.]+)}
1042      * — Additional build information, if desired.  In the case of an
1043      * {@code internal} build this will often contain the date and time of the
1044      * build. </p></li>
1045      *
1046      * </ul>
1047      *
1048      * <p> A version string {@code 10-ea} matches {@code $VNUM = "10"} and
1049      * {@code $PRE = "ea"}.  The version string {@code 10+-ea} matches
1050      * {@code $VNUM = "10"} and {@code $OPT = "ea"}. </p>
1051      *
1052      * <p> When comparing two version strings, the value of {@code $OPT}, if
1053      * present, may or may not be significant depending on the chosen
1054      * comparison method.  The comparison methods {@link #compareTo(Version)
1055      * compareTo()} and {@link #compareToIgnoreOptional(Version)
1056      * compareToIgnoreOptional()} should be used consistently with the
1057      * corresponding methods {@link #equals(Object) equals()} and {@link
1058      * #equalsIgnoreOptional(Object) equalsIgnoreOptional()}.  </p>
1059      *
1060      * <p> A <em>short version string</em>, {@code $SVSTR}, often useful in
1061      * less formal contexts, is a version number optionally followed by a
1062      * pre-release identifier:</p>
1063      *
1064      * <blockquote><pre>


1108          *         A string to interpret as a version
1109          *
1110          * @throws  IllegalArgumentException
1111          *          If the given string cannot be interpreted as a valid
1112          *          version
1113          *
1114          * @throws  NullPointerException
1115          *          If the given string is {@code null}
1116          *
1117          * @throws  NumberFormatException
1118          *          If an element of the version number or the build number
1119          *          cannot be represented as an {@link Integer}
1120          *
1121          * @return  The Version of the given string
1122          */
1123         public static Version parse(String s) {
1124             if (s == null)
1125                 throw new NullPointerException();
1126 
1127             // Shortcut to avoid initializing VersionPattern when creating
1128             // feature-version constants during startup
1129             if (isSimpleNumber(s)) {
1130                 return new Version(List.of(Integer.parseInt(s)),
1131                         Optional.empty(), Optional.empty(), Optional.empty());
1132             }
1133             Matcher m = VersionPattern.VSTR_PATTERN.matcher(s);
1134             if (!m.matches())
1135                 throw new IllegalArgumentException("Invalid version string: '"
1136                                                    + s + "'");
1137 
1138             // $VNUM is a dot-separated list of integers of arbitrary length
1139             String[] split = m.group(VersionPattern.VNUM_GROUP).split("\\.");
1140             Integer[] version = new Integer[split.length];
1141             for (int i = 0; i < split.length; i++) {
1142                 version[i] = Integer.parseInt(split[i]);
1143             }
1144 
1145             Optional<String> pre = Optional.ofNullable(
1146                     m.group(VersionPattern.PRE_GROUP));
1147 
1148             String b = m.group(VersionPattern.BUILD_GROUP);


1165                 } else {
1166                     throw new IllegalArgumentException("'+' found with neither"
1167                         + " build or optional components: '" + s + "'");
1168                 }
1169             }
1170             return new Version(List.of(version), pre, build, optional);
1171         }
1172 
1173         private static boolean isSimpleNumber(String s) {
1174             for (int i = 0; i < s.length(); i++) {
1175                 char c = s.charAt(i);
1176                 char lowerBound = (i > 0) ? '0' : '1';
1177                 if (c < lowerBound || c > '9') {
1178                     return false;
1179                 }
1180             }
1181             return true;
1182         }
1183 
1184         /**
1185          * Returns the value of the <a href="#FEATURE">feature</a> element of
1186          * the version number.
1187          *
1188          * @return The value of the feature element
1189          */
1190         public int feature() {
1191             return version.get(0);
1192         }
1193 
1194         /**
1195          * Returns the value of the <a href="#INTERIM">interim</a> element of
1196          * the version number, or zero if it is absent.
1197          *
1198          * @return The value of the interim element, or zero
1199          */
1200         public int interim() {
1201             return (version.size() > 1 ? version.get(1) : 0);
1202         }
1203 
1204         /**
1205          * Returns the value of the <a href="#UPDATE">update</a> element of the
1206          * version number, or zero if it is absent.
1207          *
1208          * @return The value of the update element, or zero
1209          */
1210         public int update() {
1211             return (version.size() > 2 ? version.get(2) : 0);
1212         }
1213 
1214         /**
1215          * Returns the value of the <a href="#PATCH">patch</a> element of the
1216          * version number, or zero if it is absent.
1217          *
1218          * @return The value of the patch element, or zero
1219          */
1220         public int patch() {
1221             return (version.size() > 3 ? version.get(3) : 0);
1222         }
1223 
1224         /**
1225          * Returns the value of the major element of the version number.
1226          *
1227          * @deprecated As of Java&nbsp;SE 10, the first element of a version
1228          * number is not the major-release number but the feature-release
1229          * counter, incremented for every time-based release.  Use the {@link
1230          * #feature()} method in preference to this method.  For compatibility,
1231          * this method returns the value of the <a href="FEATURE">feature</a>
1232          * element.
1233          *
1234          * @return The value of the feature element
1235          */
1236         @Deprecated(since = "10")
1237         public int major() {
1238             return feature();
1239         }
1240 
1241         /**
1242          * Returns the value of the minor element of the version number, or
1243          * zero if it is absent.
1244          *
1245          * @deprecated As of Java&nbsp;SE 10, the second element of a version
1246          * number is not the minor-release number but the interim-release
1247          * counter, incremented for every interim release.  Use the {@link
1248          * #interim()} method in preference to this method.  For compatibility,
1249          * this method returns the value of the <a href="INTERIM">interim</a>
1250          * element, or zero if it is absent.
1251          *
1252          * @return The value of the interim element, or zero
1253          */
1254         @Deprecated(since = "10")
1255         public int minor() {
1256             return interim();
1257         }
1258 
1259         /**
1260          * Returns the value of the security element of the version number, or
1261          * zero if it is absent.
1262          *
1263          * @deprecated As of Java&nbsp;SE 10, the third element of a version
1264          * number is not the security level but the update-release counter,
1265          * incremented for every update release.  Use the {@link #update()}
1266          * method in preference to this method.  For compatibility, this method
1267          * returns the value of the <a href="UPDATE">update</a> element, or
1268          * zero if it is absent.
1269          *
1270          * @return  The value of the update element, or zero
1271          */
1272         @Deprecated(since = "10")
1273         public int security() {
1274             return update();
1275         }
1276 
1277         /**
1278          * Returns an unmodifiable {@link java.util.List List} of the integers
1279          * represented in the <a href="#verNum">version number</a>.  The {@code
1280          * List} always contains at least one element corresponding to the <a
1281          * href="#feature">feature version number</a>.
1282          *
1283          * @return  An unmodifiable list of the integers
1284          *          represented in the version number
1285          */
1286         public List<Integer> version() {
1287             return version;
1288         }
1289 
1290         /**
1291          * Returns the optional <a href="#pre">pre-release</a> information.
1292          *
1293          * @return  The optional pre-release information as a String
1294          */
1295         public Optional<String> pre() {
1296             return pre;
1297         }
1298 
1299         /**
1300          * Returns the <a href="#build">build number</a>.
1301          *
1302          * @return  The optional build number.
1303          */
1304         public Optional<Integer> build() {


< prev index next >