Monday, September 28, 2020

Moving Toward Inline Classes: JEP 390 and the @ValueBased Annotation

Candidate JEP 390 ("Warnings for Value-Based Classes") was announced this past week by Mark Reinhold on the OpenJDK jdk-dev mailing list. This is a JDK Enhancement Proposal that may be more exciting in what it indicates (progress toward inline classes) than what it actually is (annotation and warnings about "improper attempts to synchronize on instances" of @ValueBased-annotated JDK classes that might be come inline classes).

The term "Value-based Classes" was included in the Java SE 8 Javadoc documentation, which identified the following characteristics of "instances of a value-based class" at that time:

  • "final and immutable (though may contain references to mutable objects)"
  • Implement "equals, hashCode, and toString ... solely [computed] from the instance's state and not from its identity or the state of any other object or variable"
  • Do NOT use "identity-sensitive operations such as reference equality (==) between instances, identity hash code of instances, or synchronization on an instances's intrinsic lock"
  • "Are considered equal solely based on equals()" rather than "on reference equality (==)"
  • "Instantiated through factory methods which make no committment as to the identity of returned instances" rather than providing accessible constructors
  • "Are freely substitutable when equal"

That Java SE 8 documentation also warned that "a program may produce unpredictable results if it attempts to distinguish two references to equal values of a value-based class, whether directly via reference equality or indirectly via an appeal to synchronization, identity hashing, serialization, or any other identity-sensitive mechanism." It further emphasizes, "Use of such identity-sensitive operations on instances of value-based classes may have unpredictable effects and should be avoided." This documentation remains essentially the same today (Java 15). This documentation is linked to from certain identified JDK classes' Javadoc comments. A good overview on value-based classes is available in Nicolai Parlog's blog post "Value-Based Classes."

Although some JDK classes have been identified in their Javadoc as value-based classes since Java 8, JEP 390 aims to provide the annotation @ValueBased for these types of JDK classes. The annotation is a stronger construct than a comment and is specifically intended to be used in conjunction with "warnings about improper attempts to synchronize on instances of such classes." The advantage of such an annotation is that developers can be warned about current uses in their code to synchronize on instances of classes that may one day be unsuitable for such synchronization. Because some likely significant time will pass between the availability of this warning and the actual coversion of these @ValueBased-annotated classes to inline classes (the JEP word this as, "several releases before the migration occurs"), developers will have ample opportunity to change the classes upon which they apply synchronization.

The warning about use of JDK classes for synchronization has benefit in its own right. In addition, I think this JEP is an exciting step toward inline types and the JEP is full of details about inline types. Specifically, the first paragraph of the "Motivation" section of JEP 390 states:

The Valhalla Project is pursuing a significant enhancement to the Java programming model in the form of inline classes. Such classes declare their instances to be identity-free and capable of inline or flattened representations, where instances can be copied freely between memory locations and encoded using solely the values of the instances' fields.

Perhaps the most anticipatory sentence in JEP 390 is in the second paragraph of the "Motivation" section (I've added the highlighting): "The design and implementation of inline classes is sufficiently mature that we can confidently anticipate migrating certain classes in the Java Platform to become inline classes in a future release."

The "Motivation" section of JEP 390 also enumerates the "properties" of a "candidate inline class." These are very simlar to the characteristics of "value-based classes" listed earlier:

  • "Is final"
  • "Declares only final instance fields"
  • "Extends Object, or a hierarchy of abstract classes that declare no instance fields and have no instance initialization logic"
  • "Declares only private constructors, or has deprecated its constructors for removal"
  • "Does not promise a unique instance will be created with each factory-method invocation (or any other instance creation mechanism)"
  • "Does not rely upon or expose object identity through any of its methods"
  • "Overrides toString, equals, and hashCode"
  • "Declares no synchronized methods, and discourages clients from performing synchronization"

JEP 390 also comments on the not-so-surprising closeness of the listed "properties" of "inline classes" to the characteristics of "value-based classes":

The Java Platform API uses the term value-based class to informally describe certain classes that satisfy similar constraints. If a class is described as value-based then it will probably be able to become an inline class.

JEP 390 explains that the @ValueBased annotation "will be introduced to indicate a class, interface, or method result for which no instances are expected to rely on object identity." The annotation is intended to "communicate to developers that they should exercise caution when using == or identityHashCode, and should not perform synchronization."

One of the other sections of JEP 390 that is particularly interesting to me is the section in the "Description" that lists likely "declarations in the Java Platform API and the JDK" to which the @ValueBased annotation may be applied. These include the "primitive wrapper classes" (perhaps one of the categories of most commonly used classes with synchronization that will need to be changed), the "optional classes" such as java.util.Optional, many classes in the java.time API, the java.util "collection factories", and more.

Constructs annotated with @ValueBased annotation will be highlighted in a javac warning. JEP 390 discusses how compile-time and runtime warnings will eventully become errors in some cases as @ValueBased-annotated classes become inline classes:

When a @ValueBased class becomes an inline class, the runtime warnings will be superseded by standard errors. At compile time, synchronization on an inline class type may also trigger a standard error. Compiler warnings will continue to be useful for interface types and method results.

The @ValueBased annotation and associated warnings will help developers to migrate their Java code that uses identified JDK value-based classes in a way not compatible with inline classes to safer alternatives. JEP 390 not only spells out the details of this, but also provides evidence of the growing maturity of the Project Valhalla work on inline classes.

Friday, September 25, 2020

foojay - A Place for Friends of OpenJDK

I welcome new sources of information on all things Java and was excited to see what the foojay site has to offer after Geertjan Wielenga (@GeertjanW) pointed it out to me. In this post I highlight some of the most promising characteristics of this site for this seeking new information on Java-related topics.

The About page describes the site's name: "A place for friends of OpenJDK." This relatively new Azul-sponsored community site was highlighted in Simon Ritter's 25 April 2020 post "foojay: A Place for Friends of OpenJDK." In that post, Ritter states:

For Java users and developers who depend on OpenJDK builds, finding the relevant highlights of a given update and how they may improve or otherwise impact deployments is no small task. Separating issues that have significance to a user from others would involve going through hundreds of individual issues. Following each into the Java Bug System to review details, and deducing relevance for one’s environment can be quite a challenge. In practice, few Java users or organizations will go through this level of effort.

This is where foojay's user-focused Java and OpenJDK update descriptions come in.

New Bug Fixes and Features in the OpenJDK

As the Ritter quote above demonstrates, one of the primary objectives of the foojay site is to help Java developers understand the various JDK offerings available based on OpenJDK and the changes, fixes, and new features associated with different versions of OpenJDK.

The following describes how to quickly see new features associated with various versions of OpenJDK on the foojay site:

  • The "What's New in OpenJDK?" is front and center on the Foojay page.
    • Provides overview of new features coming to recent versions of OpenJDK.
    • Click on month/year to see versions of OpenJDK with changes in that month.
    • Click on specific version of OpenJDK for that month/year to see change categories such as "Highlights", "All Issues", "Component View", and "Security / CVE View"
    • Click on category tab to see table representation of changes to that OpenJDK version in that category. This table includes different details depending on the category. The "Foojar Commentary" column of the "Highlights" table provides summary details about a particular bug or feature.

Java Version Almanac

The Java Version Almanac section of the Foojay site presents details on various versions from 1.0 to through JDK 16 as of this writing. There are, of course, generally more details in the later versions than the earlier versions, but it's interesting to see how Java and the JDK have changed. The information presented in Foojay's "Java Version Almanac" section is based upon, which "is provided by Java Champions Marc R. Hoffmann and Cay S. Horstmann".

OpenJDK Command Line Arguments

Another interesting section of the Foojay site is the section on OpenJDK's supported command-line arguments. This section shows command-line arguments for each version of OpenJDK from Java 6 through Java 16 as of this writing. This section is derived from Chris Newland's site.

Foojay Blog

Since its inception, the foojay site seems to have broaded its scope to cover additional topics related to use of Java and OpenJDK. There are several well-known Java developers/speakers who write posts for the Foojay blog. These include the following authors (not the entire list):

Although many of the bloggers on the Foojay site have their own blog sites with the same blog posts, there is an advantage to being able to see the headlines and blogs of these different authors in one place without needing to go to each author's individual blog.

Things I Like About the Foojay Site

  • Coverage of different versions of Java and OpenJDK
  • Coverage of different implementations of OpenJDK
  • Community-based with contributions from multiple individuals and sites
  • Blog posts focused on Java-related technologies
    • Even though many of these posts are available on the authors' sites, it's easier to see the headlines in a single location and click on stories of interest.
    • I like the strong focus on Java in these blog posts because Java is still my main programming language.
  • Single location for updates on what's new in the Java and OpenJDK world
    • This Azul-sponsored site nicely complements the Oracle-provided Inside Java site and a Java developer is likely to be aware of most major developments in the Javasphere if regularly reviewing these two sites.
  • Significantly fewer advertisements than many software development aggregation sites
    • Although there are mentions of Azul offerings, they are limited and not the invasive pop-up style advertisements plaguing many software development aggregation sites.
  • Backed by Azul
    • Too many blogs and other sources that I like for new information on Java tend to die out quickly and I have greater confidence in the Azul-sponsored Foojay site being around for a while.
    • The Foojay site's association with Azul means that it is associated with an OpenJDK contributor who provides their own implementation based on OpenJDK and who is a participant in the Java Community Process.


We continue to have exciting new things coming soon to a JDK near us. With the 6-month cadence of new OpenJDK releases, it can be difficult to keep up with so much change. The Foojay site is a great tool for Java developers who want to see the most important details regarding what's coming without needing to delve into bug reports and OpenJDK mailing lists.