Monday, November 23, 2020

Day Period Support in JDK 16

JDK 16 Early Access Build 25 (2020/11/18) includes changes for JDK-8247781 ("Day periods support"). As stated in the JDK 16 Early Access Build 25 Release Notes ("Day period support added to java.time formats"), the new functionality "translates day periods defined in Unicode Consortium's CLDR."

In most English-language situations using a "12-hour clock", the "day periods" might be used instead of the AM (ante meridiem) and PM (post meridiem) designators. The Unicode documentation "Day Period Rule Sets" describes day period rules like this: "Each locale can have a set of day period rules, which determine the periods during a day for use in time formats like '10:00 at night', or to select statements like 'Your email arrived last night.' If locales do not have dayPeriodRules, the computation of dayPeriods falls back to AM/PM."

As with most things, it's perhaps easiest to see this new functionality via code examples and their associated output. The first example shown here is adapted from the JDK 16 Early Access Build 25 Release Notes. Note that the "B" is used in the pattern to specify that a day period is to be used.

 * Writes the current day period out to standard output.
 * This is based on the example included with the Release Notes
 * (
public void printCurrentDayPeriod()
   final String currentDayPeriodStr
      = DateTimeFormatter.ofPattern("B").format(;
   out.println("Pattern 'B' (time now): \"" + currentDayPeriodStr + "\"");

The output for the above code sample when run in evening hours is now shown:

Pattern 'B' (time now): "in the evening"

The next code sample contains two methods, showing variations of date/time formats using the "B" format pattern letter.

 * Prints representation of supplied {@link ZonedDateTime} with hour,
 * day period, and time zone details to standard output.
 * @param zonedDateTime Date/time that will be written to standard output
 *    and will include hour, day period, and zone details.
public void printHourDayPeriodAndZone(final ZonedDateTime zonedDateTime)
   final String dateTimeStr
      = DateTimeFormatter.ofPattern("hh B, zzzz").format(zonedDateTime);
   out.println("Hour/Day Period/Zone: \"" + dateTimeStr + "\"");

 * Prints representation of supplied {@link ZonedDateTime} with hour,
 * minutes, day period, and time zone details to standard output.
 * @param zonedDateTime Date/time that will be written to standard output
 *    and will include hour, minutes, day period, and zone details.
public void printHourDayMinutePeriodAndZone(final ZonedDateTime zonedDateTime)
   final String dateTimeStr
      = DateTimeFormatter.ofPattern("K:mm B z").format(zonedDateTime);
   out.println("Hour/Minute/Day Period/Zone: \"" + dateTimeStr + "\"");

The following two lines of output are shown when the two methods above are executed during evening hours:

Hour/Day Period/Zone: "08 in the evening, Mountain Standard Time"
Hour/Minute/Day Period/Zone: "8:07 in the evening MST"

Because the output for the examples to this point were all executed in evening hours, the day period ("in the evening") has been the same for all examples executed above.

The next code listing iterates over each hour of the day to indicate different day period expressions for the different hours when Locale.US is specified. Note that the dates/times constructed in this example have non-zero fractional hours (non-zero minutes, seconds, and nanoseconds).

 * Prints Day Period phraseology for each of 24 hours of day with
 * arbitrary minutes, seconds, and nanoseconds to standard output.
public void printDayPeriodsByHour()
   out.println("===== Hours With Non-Zero Minutes/Seconds/Nanoseconds =====");
   final DateTimeFormatter dateTimeFormat = DateTimeFormatter.ofPattern("hh B");
   for (int hour = 0; hour < 24; hour++)
      final OffsetDateTime dateTime
      out.println("Hour " + hour + ": \"" + dateTimeFormat.format(dateTime) + "\"");

The output from running the code above shows how different hours correspond to different "day periods" for US.Locale. Note that this output is based on a date/time with non-zero fractional hours (times are not exact hours).

===== Hours With Non-Zero Minutes/Seconds/Nanoseconds =====
Hour 0: "12 at night"
Hour 1: "01 at night"
Hour 2: "02 at night"
Hour 3: "03 at night"
Hour 4: "04 at night"
Hour 5: "05 at night"
Hour 6: "06 in the morning"
Hour 7: "07 in the morning"
Hour 8: "08 in the morning"
Hour 9: "09 in the morning"
Hour 10: "10 in the morning"
Hour 11: "11 in the morning"
Hour 12: "12 in the afternoon"
Hour 13: "01 in the afternoon"
Hour 14: "02 in the afternoon"
Hour 15: "03 in the afternoon"
Hour 16: "04 in the afternoon"
Hour 17: "05 in the afternoon"
Hour 18: "06 in the evening"
Hour 19: "07 in the evening"
Hour 20: "08 in the evening"
Hour 21: "09 at night"
Hour 22: "10 at night"
Hour 23: "11 at night"

Because the date/time used in the example above has non-zero fractional hours, the en_US day period expressions are "at night", "in the morning", "in the afternoon", and "in the evening".

The next code snippet shows a method that ensures the formatted date/time has "exact hours" (its minutes, seconds, and nanoseconds are all zero).

 * Prints Day Period phraseology for each of 24 hours of day with
 * zero minutes, zero seconds, and zero nanoseconds to standard output.
public void printDayPeriodsByWholeHours()
   out.println("===== Exact Hours =====");
   final DateTimeFormatter dateTimeFormat = DateTimeFormatter.ofPattern("hh B");
   for (int hour = 0; hour < 24; hour++)
      final OffsetDateTime dateTime = OffsetDateTime.of(
         2020, 11, 23, hour, 0, 0, 0, ZoneOffset.UTC);
      out.println("Hour " + hour + ": \"" + dateTimeFormat.format(dateTime) + "\"");

When the above code is executed, the following output is seen:

===== Exact Hours =====
Hour 0: "12 midnight"
Hour 1: "01 at night"
Hour 2: "02 at night"
Hour 3: "03 at night"
Hour 4: "04 at night"
Hour 5: "05 at night"
Hour 6: "06 in the morning"
Hour 7: "07 in the morning"
Hour 8: "08 in the morning"
Hour 9: "09 in the morning"
Hour 10: "10 in the morning"
Hour 11: "11 in the morning"
Hour 12: "12 noon"
Hour 13: "01 in the afternoon"
Hour 14: "02 in the afternoon"
Hour 15: "03 in the afternoon"
Hour 16: "04 in the afternoon"
Hour 17: "05 in the afternoon"
Hour 18: "06 in the evening"
Hour 19: "07 in the evening"
Hour 20: "08 in the evening"
Hour 21: "09 at night"
Hour 22: "10 at night"
Hour 23: "11 at night"

The output above is mostly the same as for the output associated with dates/times that had fractional hours, but the whole hours example is different for hour 0 (day period of "midnight") and hour 12 (day period of "noon").

For my last example, I'm going to use Dominican Republic/Spanish ("es DO") for the Locale with the same code just demonstrated. Here is that output:

Hour 0: "12 de la madrugada"
Hour 1: "01 de la madrugada"
Hour 2: "02 de la madrugada"
Hour 3: "03 de la madrugada"
Hour 4: "04 de la madrugada"
Hour 5: "05 de la madrugada"
Hour 6: "06 de la mañana"
Hour 7: "07 de la mañana"
Hour 8: "08 de la mañana"
Hour 9: "09 de la mañana"
Hour 10: "10 de la mañana"
Hour 11: "11 de la mañana"
Hour 12: "12 del mediodía"
Hour 13: "01 de la tarde"
Hour 14: "02 de la tarde"
Hour 15: "03 de la tarde"
Hour 16: "04 de la tarde"
Hour 17: "05 de la tarde"
Hour 18: "06 de la tarde"
Hour 19: "07 de la tarde"
Hour 20: "08 de la noche"
Hour 21: "09 de la noche"
Hour 22: "10 de la noche"
Hour 23: "11 de la noche"

Support for "day period" presentation in formatted dates/times provides Java developers with more flexibility in expressing day period details than simply using AM and PM. All code listings shown in this post are available on GitHub.

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.

Friday, August 21, 2020

JDK16 javac xlint Warning about Default Constructors

I mentioned in my blog post "Explicit No-Arguments Constructor Versus Default Constructor" that "it is possible that one day javac will have an available lint warning to point out classes with default constructors." In that post, I referenced JDK-8071961 ("Add javac lint warning when a default constructor is created"), which has now been implemented as of JDK 16 Early Access Build #12. This post introduces that newly available javac -xlint warning.

To see this new javac -Xlint warning in action, one must download at least JDK 16 Early Access Build #12 (19 August 2020) or later.

To demonstrate the new javac -Xlint warning, we need a class with no explicit constructor so that javac will generate a "default constructor."

<rant>(By the way, a minor pet peeve of mine is when someone comments an explicit constructor with no arguments with Javadoc text that states "Default constructor." It's not really a default constructor once it's explicitly specified!)</rant>

An example of a class with no explicit constructor is available on GitHub and is shown here:
package dustin.examples.jdk16;

import static java.lang.System.out;

 * This class intentionally does NOT specify an explicit constructor
 * so that a "default constructor" will be generated and trigger the
 * new JDK 16 warning.
public class DefaultConstructor
   private String name;

   public String getName()
      return name;

   public void setName(final String newName)
      name = newName;

   public static void main(final String[] arguments)
      final DefaultConstructor instance = new DefaultConstructor();
      instance.setName(arguments.length > 0 ? arguments[0] : "");
      out.println("Hello " + instance.getName() + "!");

If we compile the new class with no explicitly specified constructor with javac provided by the OpenJDK JDK 16 Early Access Build #12 or later, we won't see the new warning demonstrated unless we export the package that class is in and enable -Xlint warnings. An example of exporting the package is available on GitHub and is shown here:
module dustin.examples
   exports dustin.examples.jdk16;

Compiling with -Xlint

When I run javac -X with the JDK 16 Early Access Build #12 compiler, I see these Xlint-related options that are now available (emphasis added):

  -Xlint                       Enable recommended warnings
        Warnings to enable or disable, separated by comma.
        Precede a key by - to disable the specified warning.
        Supported keys are:
          all                  Enable all warnings
          auxiliaryclass       Warn about an auxiliary class that is hidden in a source file, and is used from other files.
          cast                 Warn about use of unnecessary casts.
          classfile            Warn about issues related to classfile contents.
          deprecation          Warn about use of deprecated items.
          dep-ann              Warn about items marked as deprecated in JavaDoc but not using the @Deprecated annotation.
          divzero              Warn about division by constant integer 0.
          empty                Warn about empty statement after if.
          exports              Warn about issues regarding module exports.
          fallthrough          Warn about falling through from one case of a switch statement to the next.
          finally              Warn about finally clauses that do not terminate normally.
          missing-explicit-ctor Warn about missing explicit constructors in public classes in exported packages.
          module               Warn about module system related issues.
          opens                Warn about issues regarding module opens.
          options              Warn about issues relating to use of command line options.
          overloads            Warn about issues regarding method overloads.
          overrides            Warn about issues regarding method overrides.
          path                 Warn about invalid path elements on the command line.
          processing           Warn about issues regarding annotation processing.
          rawtypes             Warn about use of raw types.
          removal              Warn about use of API that has been marked for removal.
          requires-automatic   Warn about use of automatic modules in the requires clauses.
          requires-transitive-automatic Warn about automatic modules in requires transitive.
          serial               Warn about Serializable classes that do not provide a serial version ID. 
                             Also warn about access to non-public members from a serializable element.
          static               Warn about accessing a static member using an instance.
          text-blocks          Warn about inconsistent white space characters in text block indentation.
          try                  Warn about issues relating to use of try blocks (i.e. try-with-resources).
          unchecked            Warn about unchecked operations.
          varargs              Warn about potentially unsafe vararg methods
          preview              Warn about use of preview language features
          none                 Disable all warnings

As shown in these usage details, one can use -Xlint, -Xlint:all, or -Xlint:missing-explicit-ctor to see this new warning about default constructors being exposed by classes in publicly exported packages.

Compiling the new class with -Xlint, -Xlint:all, or -Xlint:missing-explicit-ctor demonstrates the new warning about default constructors being used in a formal API:


-Xlint and -Xlint:missing-explicit-ctor

As shown in the screenshots, the warning message states (emphasis added by me): "warning: [missing-explicit-ctor] class DefaultConstructor in exported package dustin.examples.jdk16 declares no explicit constructors, thereby exposing a default constructor to clients of module dustin.examples"

The warning message that javac provides when -Xlint is appropritely specified describes the issue and specifically calls out the exported package with the offending class and the name of module that exports that package.

Summary of Steps to See Default Constructor Warning

  1. Download and "install" OpenJDK 16 Early Access Build #12 (or later) from
  2. Write Java class with no explicitly specified constructor so that javac will generate a "default constructor" (example).
  3. Export package with class with no explicit constructor via a file (example).
  4. Compile class with no explicit constructor with -Xlint:all provided to the javac compiler.

Not All Classes with No Explicit Constructors Will Be Flagged

Not all Java classes that lack an explicit constructor will lead to this new warning being emitted even when a relevant -Xlint option is specified. As stated earlier, even the DefaultConstructor class used in this post's example does not lead to the warning message being generated until it's package is exported in the file. Joe Darcy explains on the OpenJDK compiler-dev mailing list:

In terms of detailed criteria to issue the new warnings, there was the usual tension in warnings between reducing false positives and false negatives. For example, warning for *any* default constructor, even in a throw-away class, would be more annoying than helpful. With some guidance from the JDK code base, criteria in the current patch are a default constructor merits a warning if:

  • The class is in a named package and the packaged has an unqualified export from its module AND
  • The class is public and, if it is a nested class, all of its lexically enclosing types are public too.

An unqualified export, where the package is available to use to any module and not just named ones, was taken to indicate classes in the package can comprise a "formal API". It would be simple to change this to an unqualified export, but I wanted to avoid unwanted instances of a new warning. If a public nested class is a non-public enclosing class, the nested class is not directly part of the exported API. These combinations of kinds of exports and nesting are tested in the tests in the DefaultCtor directory.

Why Warn on Use of Default Constructors in a "Formal API" Class?

The previously mentioned Joe Darcy post explains why this warning has been added:

Some background on the design of the warning and broader usage context, while default constructors can be convenient for informal code, they can be a bit troublesome for more formal APIs, such as the public classes of packages in the JDK. One issue is that default constructors do not have javadoc. Another is that a class that semantically should not be instantiated, say it is a solely a holder for static constants and methods, can get instantiated and subclassed. (Subclasssing such a class is an anti-pattern to allow use short names for the static members, which is no longer necessary since static imports as of Java SE 5.0.)


This seemingly small change to add this new warning about "default constructors" in "formal API" classes has required more effort than might initially be assumed. A large number of issues were written to not only introduce the xlint warning, but to clean up numerous classes throughout the JDK that triggered this warning when compiled. Furthermore, naming and logging can often be tricky and the particular warning mssage went through review and iterative changes as well.

Friday, August 7, 2020

Project Amber Design Documents on GitHub

As discussed in a Brian Goetz post on the amber-spec-experts mailing list, an effort is currently underway for "migrating design docs to GitHub." The GitHub repository is openjdk/amber-docs and it already hosts some frequently-referenced Project Amber design documents.

The project's main README states that this repository "is for design notes, presentations, guides, FAQs, and other collateral surrounding OpenJDK Project Amber." It also explains the relationship between the Amber design documents in this repository with those hosted on the OpenJDK Project Amber site: "Most documents here are written in (pandoc) Markdown, and changes made to Markdown sources are automatically formatted and pushed to the OpenJDK website.

The Amber design documents hosted on openjdk/amber-docs are currently categorized as either design-notes or guides. Here are some of the Amber design documents already hosted in the new openjdk/amber-docs GitHub repository (mostly in GitHub-friendly MarkDown format):

The moving of OpenJDK source and artifacts to GitHub via Project Skara is paying benefits already in terms of accessibility for Java developers. The moving of Amber design documents to GitHub will likewise make these documents more readily available. As a side note, the OpenJDK design discussions and decisions are also often readily available from the relatively new blog that features "news and views from the Java team at Oracle."

Although these Project Amber design documents have long been publicly available, this migration to GitHub should make them even easier to access and will likely increase awareness of and access to these documents. Undoubtedly, advantages inherent with a modern version control system will be gained including easier ability to make, review, track, audit, and contribute changes.

Saturday, August 1, 2020

Finalizing instanceof Pattern Matching and Records in JDK 16

Gavin Bierman has recently posted two approachable posts regarding instanceof pattern matching and records on the amber-spec-experts mailing list and both posts are thorough but succinct. I recommend that anyone interested in the latest state of these two Project Amber initiatives read these posts: "Finalizing in JDK 16 - Pattern matching for instanceof" and "Finalizing in JDK 16 - Records". Even for those not interested in the details, it is probably interesting to see the likelihood of instanceof pattern matching and records being finalized in JDK 16.

Pattern Matching instanceof Operator

In "Finalizing in JDK 16 - Pattern matching for instanceof," Bierman writes: "In JDK 16 we are planning to finalize two JEPs: Pattern matching for instanceof and Records." About instanceof pattern matching, Bierman states, "Adding conditional pattern matching to an expression form is the main technical novelty of our design of this feature."

The "Finalizing in JDK 16 - Pattern matching for instanceof" post talks about advantages of the instanceof pattern matching approach. Advantages discussed in the post include refactoring of a "common programming pattern" (checking for instanceof and then explicitly casting the thing checked with instanceof to the type it was checked against) to smaller code that is more readable. Another discussed advantage is the ability "to compactly express things with expressions that are unnecessarily complicated using statements."

Bierman also discusses scope issues, local pattern variable "poisoning", and how these will be dealt with using "flow scoping." About this, Bierman writes:

Java already uses flow analysis - both in checking the access of local variables and blank final fields, and detecting unreachable statements. We lean on this concept to introduce the new notion of flow scoping. A pattern variable is only in scope where the compiler can deduce that the pattern has matched and the variable will be bound. This analysis is flow sensitive and works in a similar way to the existing analyses. ... The motto is "a pattern variable is in scope where it has definitely matched". This is intuitive, allows for the safe reuse of pattern variables, and Java developers are already used to flow sensitive analyses.

The post on instanceof pattern matching ends with a discussion of the "Swiss cheese property" ("unfortunate interaction of flow scoping and shadowing [local pattern variables shadowing a field declaration]") and expresses the hope that IDEs will help developers to deal with these unfortunate interactions.


Bierman's post "Finalizing in JDK 16 - Records" provides some nice summary descriptions related to Records. The first is, "Record classes are a special kind of class that are used primarily to define a simple aggregate of values." This is immediately followed by, "Records can be thought of as nominal tuples; their declaration commits to a description of their state and given that their representation, as well as all of the interesting protocols an object might expose -- construction, property access, equality, etc -- are derived from that state description."

This post covers the "implicit declaration of a number of members" of a Record from the Record's "state description." The post also provides a brief overview of why a developer might "explicitly [provide] a canonical constructor" and how to do so. About this, Bierman writes, "The intention of a compact constructor declaration is that only validation and/or normalization code need be given in the constructor body; the remaining initialization code is automatically supplied by the compiler."

"Finalizing in JDK 16 - Records" also discusses canonical constructor accessibility, @Override, and general annotations related to Records. The post concludes by mentioning that Records can be declared locally and explains how this is an advantage for an expected common use case of Records: "Records will often be used as containers for intermediate data within method bodies. Being able to declare these record classes locally is essential to stop proliferation of classes."


The two Project Amber initiatives of instanceof pattern matching and records will be welcome additions to the Java programming language. Although these features have been available in versions of the JDK before JDK 16 as preview features, it will be their finalization (hopefully in JDK 16) that will enable many more developers to apply them in production code.

Friday, July 10, 2020

Potential Inlined JDK Classes

Earlier this week, Dan Smith posted "JEP draft: Identity Warnings for Inline Class Candidates" on the valhalla-spec-experts mailing list. The purpose of this post was to introduce a draft JEP ("Identity Warnings for Inline Class Candidates") associated with JDK-8249100.

The main intent of this JEP is to "provide warnings at compile time and runtime for behaviors that will change when certain classes of the Java SE APIs become inline classes." Although I think it's a good idea to have these warnings to help Java developers recognize coming change and opportunities for change, I find the background details provided to in this draft JDK Enhancement Proposal to be as interesting as the end objective. This draft JEP consolidates discussions and decisions discussed among many different threads and messages on the mailing lists in a single easily referenced location.

Inline Classes in Java

The "Motivation" section of the draft JEP states that inline 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." That same section also outlines two operations (monitoring/locking with synchronized and instantiation with new) that will not be supported by the identity-less inline classes. Because certain operations will not be allowed on inline classes and because some current JDK classes that may be used with these operations may be transitioned to inline classes at some point, it is desirable to have this draft JEP's proposed warnings. These warnings alert developers to their current uses of these inline class candidate JDK classes in conjunction with these operations that will not be supported on inline classes in the future (eventually an error will result).

For more background on inline classes, see the March 2020 version of the State of Valhalla document, in which Brian Goetz makes these observations:

  • "Inline classes are heterogeneous aggregates that explicitly disavow object identity."
  • Inline classes "must be immutable and cannot be layout-polymorphic."
  • "Inline classes have some restrictions compared to ordinary (identity) classes; they are final, their fields are final, and their ability to participate in inheritance is limited."
  • "Inline classes can use most mechanisms available to classes: methods, constructors, fields, encapsulation, type variables, annotations, etc"
  • "The slogan" for inline classes "is Codes like a class, works like an int."
  • "Inline types could equally be thought of as 'faster classes' or 'user-definable primitives'."

Identified JDK Inline Class Candidates

The "Description" section of the draft JEP lists several bullets of classes and groups of classes that are "likely to become inline classes." These candidate JDK inline classes are listed, as of this writing, as follows:

  • Primitive Wrapper Classes: java.lang.Byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Float, java.lang.Double, java.lang.Boolean, java.lang.Character
  • Optional Classes: java.util.Optional, java.util.OptionalInt, java.util.OptionalLong, java.util.OptionalDouble
  • Java Time Classes: java.time.Instant, java.time.LocalDate, java.time.LocalTime, java.time.LocalDateTime, java.time.ZonedDateTime, java.time.ZoneId, java.time.OffsetTime, java.time.OffsetDateTime, java.time.ZoneOffset, Duration, java.time.Period, java.time.Year, java.time.YearMonth, java.time.MonthDay, and select classes in java.time.chrono package.
  • Collections Returned from Collection Factories: java.util.List.of, java.util.List.copyOf, java.util.Set.of, java.util.Set.copyOf, java.util.Map.of, java.util.Map.copyOf, java.util.Map.ofEntries, and java.util.Map.entry
  • java.lang.Runtime.Version
  • java.lang.ProcessHandles Implementations
  • java.lang.constant.ConstantDesc Implementations (except java.lang.String)
  • Select Classes in the jdk.incubator.foreign Module

JDK Classes That Will Not Be Inlined

There are some JDK-provided classes that, at first thought, might seem like candidates to be inline classes, but turn out to have characteristics that make them unlikely to ever be transitioned. These include java.lang.String and java.math.BigInteger and java.math.BigDecimal.


The recently proposed draft JEP discussed in this post provides a centralized location for updated background details related to the currently planned inline classes feature being discussed and worked as part of Project Valhalla. Keeping in mind that this is a draft JEP about an in-work feature, this draft JEP provides insight into how inline classes will change how we write and use Java classes.