Tag Archives: JEP

JEP 223: New Version-String Scheme


JEP 223: New Version-String Scheme

Summary

Revise the JDK’s version-string scheme so that it is easier to distinguish major, minor, and security-update releases.

Goals

  • Be easily understandable by humans, and easily parsable by programs.
  • Align with current industry practices, in particular Semantic Versioning.
  • Be adoptable by existing packaging systems and platform-deployment mechanisms including RPM, dpkg, IPS, and the Java Network Launching Protocol (JNLP).
  • Eliminate the current practice of encoding two types of information in one element of the version string, i.e., the minor release number and the security level, which is difficult to decipher and results in skipping many version numbers.
  • Provide a simple API for version-string parsing, validation, and comparison.

Non-Goals

  • Change the version-string format used by any release prior to this JEP’s targeted release.

Motivation

Which release contains all of the most recent security fixes: JDK 7 Update 55, or JDK 7 Update 60?

It looks like JDK 7 Update 60 is five releases later than Update 55, so therefore it must include more security fixes, right?

That conclusion is, sadly, incorrect: These two releases both contain exactly the same security fixes. To understand this answer, you first need to understand thecurrent numbering scheme for JDK Update releases. Minor releases containing changes beyond security fixes are multiples of 20. Security releases based on the previous minor release are odd numbers incremented by five, or by six if necessary in order to keep the update number odd. To understand whether a minor release is actually more secure than an earlier release ultimately requires looking at the release notes or the source code.

What’s the difference between releases named “JDK 7 Update 60”, “1.7.0_60”, and “JDK 7u60”?

These are just different names for the same release. These differences make it difficult to identify and verify equivalent releases. A simple pointwise comparison of sequences of parsed tokens does not suffice; instead, a fairly sophisticated algorithm is needed. The use of the lower-case ‘u’ is not an industry standard and is not language-neutral.

It’s long past time for a simpler, more intuitive versioning scheme.

Description

Version numbers

A version number is a non-empty sequence of non-negative integer numerals, without leading zeroes, separated by period characters (U+002E); i.e., it matches the regular expression [1-9][0-9]*(\.(0|[1-9][0-9]*))*. The sequence may be of arbitrary length but the first three elements are assigned specific meanings, as follows:

$MAJOR.$MINOR.$SECURITY
  • $MAJOR — The major version number, incremented for a major release that contains significant new features as specified in a new edition of the Java SE Platform Specification, e.g., JSR 337 for Java SE 8. Features may be removed in a major release, given advance notice at least one major release ahead of time, and incompatible changes may be made when justified. The $MAJORversion number of JDK 8 was 8; the $MAJOR version number of JDK 9 will be 9.
  • $MINOR — The minor version number, incremented for a minor update release that may contain compatible bug fixes, revisions to standard APIs mandated by a Maintenance Release of the relevant Platform Specification, and implementation features outside the scope of that Specification such as new JDK-specific APIs, additional service providers, new garbage collectors, and ports to new hardware architectures. $MINOR is reset to zero when$MAJOR is incremented.
  • $SECURITY — The security level, incremented for a security-update release that contains critical fixes including those necessary to improve security.$SECURITY is reset to zero only when $MAJOR is incremented. A higher value of $SECURITY for a given $MAJOR value, therefore, always indicates a more secure release, regardless of the value of $MINOR.

The fourth and later elements of a version number are free for use by downstream consumers of the JDK code base. Such a consumer may, e.g., use the fourth element to identify patch releases which contain a small number of critical non-security fixes in addition to the security fixes in the corresponding security release.

The sequence of numerals in a version number is compared to another such sequence in numerical, pointwise fashion; e.g., 9.9.1 is less than 9.10.0. If one sequence is shorter than another then the missing elements of the shorter sequence are considered to be zero; e.g., 9.1.2 is equal to 9.1.2.0 but less than 9.1.2.1.

Version strings

A version string consists of a version number $VNUM, as described above, optionally followed by pre-release and build information, in the format

$VNUM(-$PRE)?(\+$BUILD)?(-$OPT)?

where:

  • $PRE, matching ([a-zA-Z0-9]+) — A pre-release identifier. Typically ea, for an early-access release that’s under active development and potentially unstable, or internal, for an internal developer build.

    When comparing two version strings, a string with a pre-release identifier is always less than one with an equal $VNUM but no such identifier. Pre-release identifiers are compared numerically when they consist only of digits, and lexicographically otherwise.

  • $BUILD, matching ([1-9][0-9]*) — The build number, incremented for each promoted build. $BUILD is reset to one when any portion of $VNUM is incremented.

    When comparing two version strings the value of $BUILD, if present, is always ignored.

  • $OPT, matching ([-a-zA-Z0-9]+) — Additional build information, if desired. In the case of an internal build this will often contain the date and time of the build.

    When comparing two version strings the value of $OPT, if present, is always ignored.

A short version string, often useful in less formal contexts, is simply$MAJOR.$MINOR.$SECURITY with trailing zero elements omitted; i.e., $SECURITY is omitted if it has the value zero, and $MINOR is omitted if both $MINOR and $SECURITYhave the value zero. A short version string may optionally end with -$PRE.

The following table compares potential version strings for JDK 9, using the existing and proposed formats:

                      Existing                Proposed
Release Type    long           short    long           short
------------    --------------------    --------------------
Early Access    1.9.0-ea-b19    9-ea    9.0.0-ea+19    9-ea
Major           1.9.0-b100      9       9.0.0+100      9
Security #1     1.9.0_5-b20     9u5     9.0.1+20       9.0.1
Security #2     1.9.0_11-b12    9u11    9.0.2+12       9.0.2
Minor #1        1.9.0_20-b62    9u20    9.1.2+62       9.1.2
Security #3     1.9.0_25-b15    9u25    9.1.3+15       9.1.3
Security #4     1.9.0_31-b08    9u31    9.1.4+8        9.1.4
Minor #2        1.9.0_40-b45    9u40    9.2.4+45       9.2.4

For reference, this table shows version strings in the new format as they would have been used, hypothetically, for some JDK 7 update and security releases:

                          Actual               Hypothetical
Release Type        long           short    long          short
------------        --------------------    -------------------
Security 2013/04    1.7.0_21-b11    7u21    7.4.10+11    7.4.10
Security 2013/06    1.7.0_25-b15    7u25    7.4.11+15    7.4.11
Minor    2013/09    1.7.0_40-b43    7u40    7.5.11+43    7.5.11
Security 2013/10    1.7.0_45-b18    7u45    7.5.12+18    7.5.12
Security 2014/01    1.7.0_51-b13    7u51    7.5.13+13    7.5.13
Security 2014/04    1.7.0_55-b13    7u55    7.6.14+13    7.5.14
Minor    2014/05    1.7.0_60-b19    7u60    7.6.14+19    7.6.14
Security 2014/07    1.7.0_65-b20    7u65    7.6.15+20    7.6.15

Dropping the initial 1 element from version numbers

This proposal drops the initial 1 element from JDK version numbers. That is, it suggests that the first release of JDK 9 will have the version number 9.0.0 rather than 1.9.0.0.

After nearly twenty years it’s clear that the second element of the current version-number scheme is the JDK’s de facto $MAJOR version number. We increment that element when we add significant new features, and also when we make incompatible changes.

We could start treating the initial element of the current scheme as the $MAJORversion number, but then JDK 9 would have the version number 2.0.0 even though everyone already refers to it as “JDK 9”. This would help no one.

If we retain the initial 1 then JDK version numbers will continue to violate the principles of Semantic Versioning and developers new to Java will continue to be confused about the difference between, e.g., 1.9 and 9.

There is some risk in dropping the initial 1. There are many ways to compare version numbers; some will work correctly, while some will not.

  • Existing code that compares version numbers by parsing their elements and comparing them numerically will continue to work, since nine is greater than one; i.e., 9.0.0 will be considered to be later than 1.8.0.
  • Existing code that skips the initial element when it has the value 1 will also continue to work, since in the new scheme the initial element will never have that value.
  • Existing code that assumes the initial element to have the value 1, however, and therefore always skips to the second element when comparing version numbers, will not work correctly; e.g., such code will consider 9.0.1 to precede 1.8.0.

Anecdotal evidence suggests that existing code in the third category is not very common, but we would welcome data to the contrary.

API

A simple JDK-specific Java API to parse, validate, and compare version strings will be defined, roughly along these lines:

package jdk.util;

import java.io.Serializable;
import java.util.Optional;

public class Version 
    implements Comparable<Version>, Serializable
{

    public static Version parse(String);
    public static Version current();

    public int major();
    public int minor();
    public int security();

    public List<Integer> version();
    public Optional<String> pre();
    public Optional<Integer> build();
    public Optional<String> optional();

    public int compareTo(Version o);

}

An equivalent C API will be defined, most likely in terms of a revisedjvm_version_info struct.

All code in the JDK that inspects and compares JDK version strings will be updated to use these APIs. Developers whose libraries or applications inspect and compare JDK version strings will be encouraged to use these APIs.

Testing

Changing the syntax and semantics of version strings will require extensive testing of all component areas. Existing tests that are independent of the JDK version string should continue to pass.

JEP 224: HTML5 Javadoc


JEP 224: HTML5 Javadoc

Summary

Enhance the javadoc tool to generate HTML5 markup.

Goals

Provide an option to javadoc to request either HTML 4 or HTML5 output. The HTML5 markup should be semantic, i.e., clearly separate meaning from style and content. The pages generated using HTML5 markup should satisfy accessibility requirements.

Non-Goals

It is a not a goal to replace the current three-frame structure of the generated HTML pages; that may be the subject of a future JEP.

Motivation

The javadoc tool currently generates pages in HTML 4.01, which is an old standard.HTML5 is the latest standard for HTML. HTML5 increases the semantic value of web pages and makes it easier to create accessible web pages.

Description

  • A command-line option will be added to javadoc to request a specific type of output markup. HTML4, which is the current output, will be the default. HTML5 will become the default in a later JDK release.
  • The semantic value of the generated HTML will be improved by using structural HTML5 elements such as header, footer, nav, etc.
  • The HTML5 markup will implement the WAI-ARIA standard for accessibility. Specific roles will be assigned to elements in the HTML document using the role attribute.
  • The -Xdoclint feature will be modified to validate input comments based upon the requested markup.

Testing

Tests will be needed to ensure that:

  • The HTML5 markup is valid
  • The HTML5 markup is accessible
  • The new command-line option works correctly
  • The HTML5 markup works across multiple browsers

The lack of automated tools to test accessibility will hamper comprehensive accessibility testing.

JEP 219: Datagram Transport Layer Security (DTLS)


JEP 219: Datagram Transport Layer Security (DTLS)

Summary

Define an API for Datagram Transport Layer Security (DTLS) version 1.0 (RFC 4347) and 1.2 (RFC 6347).

Non-Goals

  1. It is not a goal to support transport-specific interfaces (for example, DTLS for DatagramSocket).
  2. It is not a goal to support PMTU discovery.

Success Metrics

The implementation, in both client and server modes, must interoperate successfully with at least two other DTLS implementations.

Motivation

It is important to support DTLS to satisfy secure-transport requirements for the increasing number of datagram-compatible applications. RFC 4347 lists a number of reasons why TLS is not sufficient for these types of applications:

  • “TLS is the most widely deployed protocol for securing network traffic. … However, TLS must run over a reliable transport channel—typically TCP. It therefore cannot be used to secure unreliable datagram traffic.”
  • “… an increasing number of application layer protocols have been designed that use UDP transport. In particular, protocols such as the Session Initiation Protocol (SIP) and electronic gaming protocols are increasingly popular.”
  • “In many cases, the most desirable way to secure client/server applications would be to use TLS; However, the requirement for datagram semantics automatically prohibits use of TLS. Thus, a datagram-compatible variant of TLS is very desirable.”

Protocols that support DTLS include, but are not limited, to:

  • RFC 5238, Datagram Transport Layer Security (DTLS) over the Datagram Congestion Control Protocol (DCCP)
  • RFC 6083, Datagram Transport Layer Security (DTLS) for Stream Control Transmission Protocol (SCTP)
  • RFC 5764, Datagram Transport Layer Security (DTLS) Extension to Establish Keys for the Secure Real-time Transport Protocol (SRTP)
  • RFC 7252, Constrained Application Protocol (CoAP)

Google Chrome and Firefox now support DTLS-SRTP for Web Real-Time Communication (WebRTC). DTLS version 1.0 and 1.2 are supported by the major TLS vendors and implementations including OpenSSL, GnuTLS, and Microsoft SChannel.

Description

We expect the DTLS API and implementation to be fairly small. The new API should be transport-independent and similar to javax.net.ssl.SSLEngine. Further details on the API will be added here as the work progresses. Some initial design considerations are as follows:

  1. The DTLS API and implementation will not manage read timeouts. It will be the responsibility of the application to determine an appropriate timeout value and when and how to trigger the timeout event.
  2. A new API will likely be added to set the maximum application datagram size (PMTU minus the DTLS per-record overhead). If the size is not specified explicitly, however, then the DTLS implementation should adjust the size automatically. If a fragment is lost two or three times, the implementation may reduce the size of the maximum application datagram size until it is small enough.
  3. The DTLS implementation should consume or produce at most one TLS record for each unwrap or wrap operation, so that the record can be delivered in the datagram layer individually or can be reassembled more easily if the delivery is out of order.
  4. It is the application’s responsibility to assemble the out-of-order application data accordingly if necessary. The DTLS API should provide access to the application data in each DTLS message.

JEP 213: Milling Project Coin


Issue 8042880
Depends 8062373: Project Coin: diamond and inner classes
Relates to 8061549: Complete the removal of underscore from the set of legal identifier names
7196163: Project Coin: Allow effectively final variables to be used as resources in try-with-resources
7196160: Project Coin: allow @SafeVarargs on private methods

Summary

The small language changes included in Project Coin / JSR 334 as part of JDK 7 / Java SE 7 have been easy to use and have worked well in practice. However, several amendments could address a few rough edges of those changes. In addition, using underscore ("_") as an identifier, which generates a warning as of Java SE 8, should be turned into an error in Java SE 9.

Non-goals

This JEP does not propose to run a “Coin 2.0” effort or to generally solicit new language proposals.

Description

Four small amendments to the Java Programming Language are proposed:

  1. Allow @SafeVargs on private instance methods. The @SafeVarargsannotation can only be applied to methods which cannot be overridden, including static methods and final instance methods. Private instance methods are another use case that @SafeVargs could accommodate.
  2. Allow effectively-final variables to be used as resources in the try-with-resources statement. The final version of try-with-resources statement in Java SE 7 requires a fresh variable to be declared for each resource being managed by the statement. This was a change from earlier iterations of the feature. The public review draft of JSR 334 discusses the rationale for the change from the early draft review version of try-with-resource which allowed an expression managed by the statement. The JSR 334 expert group was in favor of an additional refinement of try-with-resources: if the resource is referenced by a final or effectively final variable, a try-with-resources statement can manage the resource without a new variable being declared. This restricted expression being managed by a try-with-resources statement avoids the semantic issues which motivated removing general expression support. At the time the expert group settled on this refinement, there was insufficient time in the release schedule to accommodate the change.
  3. Allow diamond with inner classes if the argument type of the inferred type is denotable. Because the inferred type using diamond with an inner class constructor could be outside of the set of types supported by the signature attribute, using diamond with inner classes was disallowed in Java SE 7. As noted in the JSR 334 proposed final draft, it would be possible to ease this restriction if the inferred type was denotable.
  4. Complete the removal, begun in Java SE 8, of underscore from the set of legal identifier names.

In the space of Java language changes, these refinements are very small changes. The @SafeVarags change might only involve changing a sentence or two of the specification with a similarly sized change in javac. However, as with any Java language change, care must be taken to handle all the pieces of the platform that need updating.

Testing

The language changes would require the usual unit and regression tests for javac. The JCK compiler suite would need to be updated, both positive tests and negative tests.