Monday, September 27, 2021

More Frequent Java Long-Term Releases

A little over four years ago, Mark Reinhold (Chief Architect of the Java Platform Group at Oracle) stated in his blog post "Moving Java Forward Faster": "For Java to remain competitive it must not just continue to move forward — it must move forward faster." In that post, Reinhold proposed "that after Java 9 we adopt a strict, time-based model with a new feature release every six months, update releases every quarter, and a long-term support release every three years." Reinhold stated that the motivation for this was that Java "must move forward faster ... for Java to remain competitive." Recently, a little over four years since the "Moving Java Forward Faster" post, Reinhold has posted "Moving Java Forward Even Faster."

Mark Reinhold's proposal in "Moving Java Forward Even Faster" is to "ship an LTS release every two years" instead of shipping a long-term support (LTS) release every three years as has been done since the 2017 proposal was implemented. Reinhold adds, "This change will give both enterprises, and their developers, more opportunities to move forward" and "will also increase the attractiveness of the non-LTS feature releases."

In the "Moving Java Forward Even Faster" post, Reinhold explains the motivation for reducing the time between LTS releases from three years to two years: "Developers are excited about the new features — which is great! Many are frustrated, however, that they cannot use them right away since their employers are only willing to deploy applications on LTS releases, which only ship once every three years."

Reinhold posted a similar message to the OpenJDK general discussion mailing list. In that message, he points out that "the LTS release following JDK 17 would thus be JDK 21 (in 2023), rather than JDK 23 (in 2024)." Reinhold also points out, "This change would, if accepted, have no effect on the main-line feature releases developed in the JDK Project. Every such release is intended to be stable and ready for production use, whether it's an LTS release or not."

Reinhold concludes his message with a request for feedback via comments and questions. There have already been some interesting responses:

  • Volker Simonis has replied on behalf of the Amazon Corretto team: "I'd like to express our support for the new JDK LTS release cadence proposal. We think this is the right step forward to keep the OpenJDK project vibrant and relevant with benefits for both developers and enterprises."
  • Martijn Verburg has replied on behalf of the Microsoft Java Engineering Team: "We would also like to endorse the 2-year LTS proposal for builds of OpenJDK. Since most of the end-user ecosystem prefers to have the extra stability of an LTS, this is a great way to encourage them with their modernization efforts!"
  • Gil Tene has replied on behalf of Azul: "I'd like to express our strong support for this proposal to move to a more frequent LTS cadence in OpenJDK."
    • Tene adds, "It does come with an extra maintenance burden for the community as a whole, but that burden is well worth it in our opinion."
  • Andrew Hale of RedHat replied: "So, from me it's a rather nervous yes, but." Hale discussed why the decision was "nuanced" and depends on the perspective taken:
    • "As developers of Java as well as users of it, we're perhaps biased in favour of new features, and we're less likely to feel the adverse effects of the upgrade treadmill."
    • "From my point of view as an engineer, moving to a two-year LTS cycle is broadly positive."
    • "Certifying libraries to run on a new Java release can take months of effort, and no-one is going to welcome having to do so more frequently."
    • "Many of our end users have been highly resistant to upgrading to new Java releases."
  • RĂ©mi Forax has replied: "I've discussed with quite a lot of people during this week, most of them prefer a 2 year schedule for a LTS. 2 years is good for application developers, 3 years is better for library maintainers. There is at least 10x more application developers."

The Oracle Java SE Support Roadmap has been updated to reflect the two-year candence for LTS releases. It now states (I added the emphasis), "Oracle will designate only certain releases as Long-Term-Support (LTS) releases. Java SE 7, 8, 11 and 17 are LTS releases. Oracle intends to make future LTS releases every two years meaning the next planned LTS release is Java 21 in September 2023."

As a developer who uses the latest JDK releases for personal projects (and often even "plays" with the OpenJDK Early-Access Builds) and then deals with the frustration of using older versions of the JDK on different projects in my "day jobs," I believe that reducing the wait between LTS releases from three years to two years will be welcome.

Related Resources

Saturday, September 25, 2021

JDK 18: Code Snippets in Java API Documentation

OpenJDK 18 Early-Access Build 16 (2021/9/23) is now available and includes the implementation for JEP 413 ("Code Snippets in Java API Documentation"), which is targeted for JDK 18. The objective of JEP 413 is to "introduce an @snippet tag for JavaDoc's Standard Doclet, to simplify the inclusion of example source code in API documentation" and the JEP itself covers the syntax of and features supported by the Javadoc {@snippet} tag.

JEP 413 introduces the new {@snippet } Javadoc tag:

We introduce a new inline tag, {@snippet ...}, to declare code fragments to appear in the generated documentation. It can be used to declare both inline snippets, where the code fragment is included within the tag itself, and external snippets, where the code fragment is read from a separate source file.

The JEP has far more details on what is supported by {@snippet } and what its syntax is. This post provides a small taste of what {@snippet } brings to Javadoc-based documentation and the code listings included in this post are available on GitHub.

This first contrived code listing makes use of {@snippet }:

package dustin.examples.jdk18.javadoc;

/**
 * Demonstrates {@code @snippet} Javadoc tag targeted for JDK
 * as part of JEP 413 (AKA Bug JDK-8201533):
 * <ul>
 *     <li>https://openjdk.java.net/jeps/413</li>
 *     <li>https://bugs.openjdk.java.net/browse/JDK-8201533</li>
 * </ul>
 *
 * An instance of this class is obtained via my {@link #newInstance()} method
 * rather than via a constructor.
 *
 * {@snippet :
 *    final SnippetExample instance = SnippetExample.newInstance(); // @highlight substring="newInstance"
 *    instance.processIt();
 * }
 */
public class SnippetExample
{
    /**
     * No-arguments constructor not intended for public use.
     * Use {@link #newInstance()} instead to get an instance of me:
     * {@snippet :
     *    final SnippetExample instance = SnippetExample.newInstance();   // @highlight substring="newInstance"
     * }
     */
    private SnippetExample()
    {
    }

    /**
     * Preferred approach for obtaining an instance of me.
     *
     * @return Instance of me.
     */
    public SnippetExample newInstance()
    {
        return new SnippetExample();
    }

    /**
     * Performs valuable processing.
     */
    public void processIt()
    {
    }
}

When the above code is run through the javadoc tool with the -private option, code snippets are generated in the HTML for the class and no-arguments constructor. Note also that the "highlighted" sections have bold emphasis in the generated HTML.

Generated class-level documentation with snippet:

Generated method-level documentation with snippet:

One area where I think the {@snippet } may be particularly useful is in package documentation. A code example of use for a package description is shown in the next code listing for package-info.java.

/**
 * Examples and demonstrations of Javadoc-related capabilities.
 *
 * The main entrypoint for the snippets example is the {@link SnippetExample} class:
 * {@snippet :
 *    final SnippetExample instance = SnippetExample.newInstance();  // @highlight substring="SnippetExample" @link substring="SnippetExample.newInstance()" target="SnippetExample#newInstance()"
 * }
 */
package dustin.examples.jdk18.javadoc;

The generated HTML output for this package-level documentation is shown in the next screenshot.

One of the challenges in including code snippets in Javadoc-based documentation has been that the tags used to present the code (such as <pre>, <code>, and {@code}) can make the Javadoc comment less readable when viewed in source directly instead of via the generated HTML. The {@snippet } Javadoc tag can make the code presentation better for the generated HTML while being less distracting in the source code itself. JEP 413 addresses the shortcomings of current approaches for including code snippets in Javadoc and summarizes how {@snippet } addresses those shortcomings:

A better way to address all these concerns is to provide a new tag with metadata that allows the author to implicitly or explicitly specify the kind of the content so that it can be validated and presented in an appropriate manner. It would also be useful to allow fragments to be placed in separate files that can be directly manipulated by the author's preferred editor.

JEP 413 contains far more details on application of {@snippet }, including the ability to reference code contained in external files.

Friday, September 17, 2021

Java's Optional Does Not Supplant All Traditional if-null-else or if-not-null-else Checks

Java's addition of java.util.Optional has been welcome and had led to more fluent code for methods that cannot always return non-null values. Unfortunately, Optional has been abused and one type of abuse has been overuse. I occasionally have run across code that makes use of Optional when there is no clear advantage over using null directly.

A red flag that can tip off when Optional is being used for no advantage over checking for null directly is when calling code employs Optional.ofNullable(T) against the returned value from the method it has just invoked. As with all "red flags," this doesn't mean it's necessarily a bad thing to pass the returned value from a method to Optional.ofNullable(T) (in fact, it is necessary to pass to APIs expecting Optional), but it is common for this approach to be used to provide no real value over using the returned value directly and checking it for null.

Before Optional was available, code to check for null returned from a method and acting one way for null response and another way for non-null response is shown next (all code snippets in this post are available on GitHub).

/**
 * Demonstrates approach to conditional based on {@code null} or
 * not {@code null} that is traditional pre-{@link Optional} approach.
 */
public void demonstrateWithoutOptional()
{
    final Object returnObject = methodPotentiallyReturningNull();
    if (returnObject == null)
    {
        out.println("The returned Object is null.");
    }
    else
    {
        out.println("The returned object is NOT null: " + returnObject);
        // code processing non-null return object goes here ...
    }
}

For this basic conditional, it's rarely necessary to involve Optional. The next code snippet is representative of the type of code I've occassionally seen when the developer is trying to replace the explicit null detection with use of Optional:

/**
 * Demonstrates using {@link Optional} in exactly the manner {@code null}
 * is often used (conditional on whether the returned value is empty or
 * not versus on whether the returned value is {@code null} or not).
 */
public void demonstrateOptionalUsedLikeNullUsed()
{
    final Optional<Object> optionalReturn
       = Optional.ofNullable(methodPotentiallyReturningNull());
    if (optionalReturn.isEmpty())
    {
        out.println("The returned Object is empty.");
    }
    else
    {
        out.println("The returned Object is NOT empty: " + optionalReturn);
        // code processing non-null return object goes here ...
    }
}

The paradigm in this code is essentially the same as the traditional null-checking code, but uses Optional.isEmpty() to perform the same check. This approach does not add any readability or other advantage but does come at a small cost of an additional object instantiation and method call.

A variation of the above use of Optional is to use its ifPresent(Consumer) method in conjunction with its isEmpty() method to form the same basic logic of doing one thing if the returned value is present and another thing if the returned value is empty. This is demonstrated in the following code.

/**
 * Demonstrates using {@link Optional} methods {@link Optional#ifPresent(Consumer)}
 * and {@link Optional#isEmpty()} in similar manner to traditional condition based
 * on {@code null} or not {@code null}.
 */
public void demonstrateOptionalIfPresentAndIsEmpty()
{
    final Optional<Object> optionalReturn
       = Optional.ofNullable(methodPotentiallyReturningNull());
    optionalReturn.ifPresent(
       (it) -> out.println("The returned Object is NOT empty: " + it));
    if (optionalReturn.isEmpty())
    {
        out.println("The returned object is empty.");
    }
}

This code appears bit shorter than the traditional approach of checking the returned value directly for null, but still comes at the cost of an extra object instantiation and requires two method invocations. Further, it just feels a bit weird to check first if the Optional is present and then immediately follow that with a check if it's empty. Also, if the logic that needed to be performed was more complicated than writing out a message to standard output, this approach becomes less wieldy.

Conclusion

Code that handles a method's return value and needs to do one thing if the returned value is null and do another thing if the returned value is not null will rarely enjoy any advantage of wrapping that returned value in Optional simply to check whether it's present or empty. The wrapping of the method's returned value in an Optional is likely only worth the costs if that Optional is used within fluent chaining or APIs that work with Optional.

Wednesday, September 15, 2021

The Case of the Missing JEPs

The JDK Enhancement-Proposal (JEP) process is "for collecting, reviewing, sorting, and recording the results of proposals for enhancements to the JDK and for related efforts, such as process and infrastructure improvements." JEP 0 is the "JEP Index" of "all JDK Enhancement Proposals, known as JEPs." This post provides a brief overview of current JDK Enhancement Proposals and discusses the surprisingly mysterious disappearance of two JEPs (JEP 187 and JEP 145).

JDK Enhancement Proposal Overview

The JEPs in the JEP Index with single-digit numbers are "Process" type JEPs and are currently:

The JEPs in the JEP Index with two-digit numbers are "Informational" type JEPs are are currently:

The remainder of the listed JEPs (with three-digit numbers) in the JEP Index are "Feature" type JEPs and currently range in number from JEP-101 ("Generalized Target-Type Inference") through JEP 418 ("Internet-Address Resolution SPI") (new candidate JEP as of this month [September 2021]).

Finally, there are some JEPs that do not yet have JEP numbers and which are shown in the under the heading "Draft and submitted JEPs" The JEPs in this state do not yet have their own JEP numbers, but instead are listed with a number in the JDK Bug System (JBS).

Originally, a JEP could exist in one of several different "JEP 1 Process States":

  • Draft
  • Posted
  • Submitted
  • Candidate
  • Funded
  • Completed
  • Withdrawn
  • Rejected
  • Active

The explanation of evolved potential JEP states is described in "JEP draft: JEP 2.0, draft 2." This document has a "Workflow" section that states that the "revised JEP Process has the following states and transitions for Feature and Infrastructure JEPs" and shows a useful graphic of these workflows. This document also describes the states of a Feature JEP:

  • Draft
  • Submitted
  • Candidate
  • Proposed to Target
  • Targeted
  • Integrated
  • Complete
  • Closed/Delivered
  • Closed/Rejected
  • Proposed to Drop

Neither these documented states for Feature JEPs nor the additional text that describes these state transitions describes a JEP with a JEP number (rather than a JBS number) being completely removed and this is what makes the disappearance of JEP 187 ("Serialization 2.0") and JEP 145 ("Cache Compiled Code") unexpected.

 

The Disappearance of JEP 187 ("Serialization 2.0")

JEP 187 is not listed in the JEP Index, but we have the following evidence that it did exist at one time:

It's surprisingly difficult to find any explanation for what happened to JEP 187. Unlike fellow serialization-related JEP 154 ("Remove Serialization") which has been moved to status "Closed / Withdrawn", JEP 187 appears to have been removed completely rather than being present with a "Closed / Withdrawn" status or "Closed / Rejected" status. Adding to the suspicious circumstances surrounding JEP 187, two requests on OpenJDK mailing lists regarding the state of this JEP (14 December 2014 on core-libs-dev and 6 September 2021 on jdk-dev) have so far gone unanswered.

The reasons for the complete disappearance of JEP 187 can be insuated from reading the "exploratory document" titled "Towards Better Serialization" (June 2019). I also previously touched on this in my post "JDK 11: Beginning of the End for Java Serialization?"

 

The Disapperance of JEP 145 ("Cache Compiled Code")

Like JEP 187, JEP-145 is not listed in the JEP Index, but there is evidence that it did exist at one time:

Also similarly to JEP 187, it is surprisingly difficult to find explanations for the removal of JEP 145. There is a StackOverflow question about its fate, but the responses are mostly speculative (but possible).

The most prevalent speculation regarding the disappearance of JEP 145 is that it is not needed due to Ahead-of-Time (AOT) compilation.

 

Conclusion

It seems that JEP 187 ("Serialization 2.0") and JEP 145 ("Cache Compiled Code") have both been rendered obsolete by changing developments, but it is surprising that they've vanished completely from the JEP Index rather than being left intact with a closed or withdrawn state.

Thursday, September 9, 2021

Surprisingly High Cost of Java Variables with Capitalized Names

I've read hundreds of thousands or perhaps even millions of lines of Java code during my career as I've worked with my projects' baselines; read code from open source libraries I use; and read code examples in blogs, articles, and books. I've seen numerous different conventions and styles represented in the wide variety of Java code that I've read. However, in the vast majority of cases, the Java developers have used capitalized identifiers for classes, enums and other types and used camelcase identifiers beginning with a lowercase letter for local and other types of variables (fields used as constants and static fields have sometimes had differening naming conventions). Therefore, I was really surprised recently when I was reading some Java code (not in my current project's baseline thankfully) in which the author of the code had capitalized both the types and the identifiers of the local variables used in that code. What surprised me most is how difficult this small change in approach made reading and mentally parsing that otherwise simple code.

The following is a represenative example of the style of Java code that I was so surprised to run across:

Code Listing for DuplicateIdentifiersDemo.java

package dustin.examples.sharednames;

import java.util.Date;
import java.util.List;
import java.util.concurrent.TimeUnit;

import static java.lang.System.out;

/**
 * Demonstrates ability to name variable exactly the same as type,
 * despite this being a really, really, really bad idea.
 */
public class DuplicateIdentifiersDemo
{
    /** "Time now" at instantiation, measured in milliseconds. */
    private final static long timeNowMs = new Date().getTime();

    /** Five consecutive daily instances of {@link Date}. */
    private final static List<Date> Dates = List.of(
            new Date(timeNowMs - TimeUnit.DAYS.toMillis(1)),
            new Date(timeNowMs),
            new Date(timeNowMs + TimeUnit.DAYS.toMillis(1)),
            new Date(timeNowMs + TimeUnit.DAYS.toMillis(2)),
            new Date(timeNowMs + TimeUnit.DAYS.toMillis(3)));

    public static void main(final String[] arguments)
    {
        String String;
        final Date DateNow = new Date(timeNowMs);
        for (final Date Date : Dates)
        {
            if (Date.before(DateNow))
            {
                String = "past";
            }
            else if (Date.after(DateNow))
            {
                String = "future";
            }
            else
            {
                String = "present";
            }
            out.println("Date " + Date + " is the " + String + ".");
        }
    }
}

The code I encountered was only slightly more complicated than that shown above, but it was more painful for me to mentally parse than it should have been because of the naming of the local variables with the exact same names as their respective types. I realized that my years of reading and mentally parsing Java code have led me to intuitively initially think of identifiers beginning with a lowercase letter as variable names and identifiers beginning with an uppercase letter as being type identifiers. Although this type of instinctive assumption generally allows me to more quickly read code and figure out what it does, the assumption in this case was hindering me as I had to put special effort into not allowing myself to think of some occurrences of "String" and "Date" as variables names and occurrences as class names.

Although the code shown above is relatively simple code, the unusual naming convention for the variable names makes it more difficult than it should be, especially for experienced Java developers who have learned to quickly size up code by taking advantage of well-known and generally accepted coding conventions.

The Java Tutorials section on "Java Language Keywords" provides the "list of keywords in the Java programming language" and points out that "you cannot use any of [the listed keywords] as identifiers in your programs." It also mentions that literals (but not keywords) true, false, and null also cannot be used as identifiers. Note that this list of keywords includes the primitive types such as boolean and int, but does not include identifiers of reference types such as String, Boolean, and Integer.

Because very close to all Java code that I had read previously used lowercase first letters for non-constant, non-static variable names, I wondered if that convention is mentioned in the Java Tutorial section on naming variables. It is. That "Variables" section states: "Every programming language has its own set of rules and conventions for the kinds of names that you're allowed to use, and the Java programming language is no different. ... If the name you choose consists of only one word, spell that word in all lowercase letters. If it consists of more than one word, capitalize the first letter of each subsequent word. The names gearRatio and currentGear are prime examples of this convention."

Conclusion

I've long been a believer in conventions that allow for more efficient reading and mental parsing of code. Running into this code with capitalized first letters for its camelcase variable name identifiers reminded me of this and has led me to believe that the greater the general acceptance of a convention for a particular language, the more damaging it is to readability to veer from that convention.

Friday, March 26, 2021

Implementing equals(Object) with instanceof Pattern Matching

Pattern matching for the instanceof operator was introduced as a preview feature with JDK 14 and was finalized with JDK 16. Because instanceof pattern matching is finalized for JDK 16, it is not surprising to now see changes being made to the JDK to take advantage of pattern matching for the instanceof operator. These changes to the JDK to leverage instanceof pattern matching can provide ideas and examples for where to begin applying this in our own code. In this post, I look at the use of instanceof pattern matching in implementation of the ubiquitous equals(Object) methods.

In a message posted to the core-libs-dev OpenJDK mailing list related to a code review for JDK-8263358 ("Update java.lang to use instanceof pattern variable"), Brian Goetz provided a reminder that a standard approach used in implementation of equals(Object) can now be modified to take advantage of pattern matching for instanceof.

In the message, Goetz uses an example of how we have often implemented equals(Object) (but using instanceof pattern matching in this example consistent with the past):

if (!(o instanceof Key that)) return false;
return name == that.name && Arrays.equals(ptypes, that.ptypes);

Goetz points out that this can now be written with a single statement, in this manner:

return (o instanceof Key that)
   && name == that.name
   && Arrays.equals(ptypes, that.ptypes);

Goetz's message concludes with this:

The use of "if it's not, return false" is a holdover from when we couldn't express this as a single expression (which is almost always preferable), which means we had to fall back to control flow. Now we don't have to.

A new commit was made based on Goetz's feedback and that commit is Commit e9d913152cefda827e01c060a13f15eacc086b33. One can review the several changes associated with this commit to see multiple statements converted into single statements in the various equals(Object) methods.

Being able to use instanceof pattern matching to implement equals(Object) with one fewer statement is a small improvement that is nevertheless welcome.

Saturday, February 27, 2021

Java NullPointerException Avoidance and Enhancement Tactics

An encountered NullPointerException can be a useful mechanism for highlighting when a certain code flow or certain data has led to unexpected results (and the messages provided by NullPointerException are much improved with JDK 15). However, there are other times when the presence of null is not an exceptional condition and for those such cases there are several tactics that can be used to easily and cleanly avoid an unwanted NullPointerException. Even when the occurrence of a NullPointerException helps identify problems, there are other tactics we can use to make the most of these opportunities.

The code samples featured in this post are part of class NullSafeTactics and its full source code is available on GitHub.

Contents

Elegantly Avoiding Unnecessary NullPointerExceptions

Implicit Java String Conversion

There are often times when we want the string representation of something that is potentially null and we do not want the access of that string representation to result in a NullPointerException. An example of this is when we log certain conditions and the context we include in the logged message includes a variable or field that is null. It is highly unlikely in such a case that we want a NullPointerException to be possibly thrown during the attempted logging of some potentially different condition. Fortunately, Java's string conversion is often available in these situations.

Even when the field variable NULL_OBJECT of type Object is null, the following code will NOT result in a NullPointerException thanks to Java's string conversion handling a null implicitly and converting it to the "null" string instead.

/**
 * Demonstrates that Java string conversion avoids {@link NullPointerException}.
 */
public void demonstrateNullSafeStringConversion()
{
   executeOperation(
      "Implicit Java String Conversion",
      () -> "The value of the 'null' object is '" + NULL_OBJECT + "'.");
}

The output from running the above code snippet demonstrates that the NullPointerException does not get thrown.

Feb 25, 2021 9:26:19 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Implicit Java String Conversion' completed without exception!

The implicit Java string conversion avoided a NullPointerException. When toString() is explicitly called on that same null, a NullPointerException is encountered. This is shown in the next code listing and the output it leads to is shown after the code listing.

/**
 * Demonstrates that explicit {@link Object#toString()} on {@code null} leads to
 * {@link NullPointerException}.
 */
public void demonstrateNullUnsafeExplicitToString()
{
   executeOperation(
      "Unsafe Explicit toString() Invocation on null",
      () -> "The value of the 'null' object is '" + NULL_OBJECT.toString() + "'.");
}
Feb 25, 2021 9:32:06 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
SEVERE: Exception encountered while trying to run operation for demonstration 'Unsafe Explicit toString() Invocation on null': java.lang.NullPointerException: Cannot invoke "Object.toString()" because "dustin.examples.nullsafe.tactics.NullSafeTactics.NULL_OBJECT" is null

Note that these examples in this post have been executed with a JDK 17 early access release, so the NullPointerExceptions shown in this post benefit from the better NPE messages introduced with JDK 14 (and are enabled by default since JDK 15).

Null-safe String Representation with String.valueOf(Object)

Allowing Java's implicit string conversion to represent null as the "null" string is the cleanest and easiest way to handle null when constructing strings. However, there are many times when we need a string representation of a Java object when implicit string conversion is not available. In such cases, String.valueOf(Object) can be used to achieve functionality similar to the implicit string conversion. When an object is passed to String.valueOf(Object), that method will return the results of the object's toString() if that object is not null or will return the "null" string if the object is null.

The following code listing demonstrates String.valueOf(Object) in action and the output from running that code is shown after the code listing.

/**
 * Demonstrates that {@link String#valueOf(Object)} will render {@code null} safely
 * as "null" string.
 *
 * In many cases, use of {@link String#valueOf(Object)} is unnecessary because Java's
 * string conversion will perform the same effect. {@link String#valueOf(Object)} is
 * necessary when Java is not able to implicitly convert to a {@link String}.
 *
 * See also https://marxsoftware.blogspot.com/2009/04/value-of-stringvalueof.html.
 */
public void demonstrateNullSafeStringValueOf()
{
   executeOperation(
      "Null-safe String Representation with String.valueOf(Object)",
      () -> "The value of the 'null' object is '" + String.valueOf(NULL_OBJECT) + "'.");
}
Feb 25, 2021 10:05:52 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Null-safe String Representation with String.valueOf(Object)' completed without exception!

There are several overloaded versions of String#valueOf accepting parameter types other than Object, but they all behave similarly.

Null-safe String Representation with Objects.toString(Object)

The Objects class provides several methods to allow for elegant handling of potential nulls. One of these, Objects.toString(Object) works exactly like the just-discussed String.valueOf(Object). In fact, as described in the post "String.valueOf(Object) versus Objects.toString(Object)", the Objects.toString(Object) method delegates to the String.valueOf(Object) method.

The following code listing demonstrates use of Objects.toString(Object) and the output from running it follows the code listing.

/**
 * Demonstrates that {@link Objects#toString(Object)} will render {@code null} safely
 * as "null" string.
 *
 * In many cases, use of {@link Objects#toString(Object)} is unnecessary because Java's
 * string conversion will perform the same effect. {@link Objects#toString(Object)} is
 * necessary when Java is not able to implicitly convert to a {@link String}.
 */
public void demonstrateObjectsToString()
{
   executeOperation(
      "Null-safe String Representation with Objects.toString(Object)",
      () -> "The value of the 'null' object is '" + Objects.toString(NULL_OBJECT) + "'.");
}
Feb 25, 2021 10:19:52 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Null-safe String Representation with Objects.toString(Object)' completed without exception!

I tend to use String.valueOf(Object) instead of Objects.toString(Object) because the latter calls the former anyway and because there are overloaded versions of String#valueOf.

Null-safe String Representation with Objects.toString(Object, String)

The approaches covered so far in this post (implicit string conversion, String#valueOf methods, and Objects.toString(Object)) all result in the "null" string when a null is presented to them. There are times when we may prefer to have something other than the "null" string be presented as the string representation of null. An example of this is when we want to return an empty string from a method rather than returning null from a method. The following code listing demonstrates using Objects.toString(Object, String) to have an empty string be provided when first passed-in argument turns out to be null.

/**
 * Demonstrates that {@link Objects#toString(Object, String)} will render {@code null}
 * potentially safely as the "default" string specified as the second argument.
 *
 * In many cases, use of {@link Objects#toString(Object, String)} is unnecessary because
 * Java's string conversion will perform the same effect. {@link Objects#toString(Object)}
 * is necessary when Java is not able to implicitly convert to a {@link String} or when
 * it is desired that the string representation of the {@code null} be something other
 * than the "null" string.
 */
public void demonstrateObjectsToStringWithDefault()
{
   executeOperation(
      "Null-safe String Representation with Objects.toString(Object,String) Using Empty String Default",
      () -> "The value of the 'null' object is '" + Objects.toString(NULL_OBJECT, "") + "'.");
}
Feb 25, 2021 10:33:16 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Null-safe String Representation with Objects.toString(Object,String) Using Empty String Default' completed without exception!

Default Value Replacement of null for Any Object

The JDK-provided methods covered so far are useful for safely acquiring string representation of objects that might be null. Sometimes, we may want to handle a potential instance that might be null of a class other than String. In that case, the Objects.requireNonNullElse(T, T) method allows specification of a default value that should be used if the object in question (first parameter to the method) is null. This is demonstrated with the following code listing and its accompanying output that follows it.

/**
 * Demonstrates that {@link Objects#requireNonNullElse(Object, Object)} will render
 * {@code null} safely for any potential {@code null} passed to it by returning the
 * supplied default instead when the object in question is {@code null}. Two
 * examples are included in this method's demonstration:
 * 
    *
  1. {@code null} {@link Object} safely rendered as custom supplied default "null" string
  2. *
  3. {@code null} {@link TimeUnit} safely rendered as custom supplied default {@link TimeUnit#SECONDS}
  4. *
* * In many cases, use of {@link Objects#requireNonNullElse(Object, Object)} is not * necessary because Java's string conversion will perform the same effect. * {@link Objects#requireNonNullElse(Object, Object)} is necessary when Java is not * able to implicitly convert to a {@link String} or when the potentially {@code null} * object is not a {@link String} or when the object to have a default returned * when it is {@code null} is of class other than {@link String}. */ public void demonstrateNullSafeObjectsRequireNonNullElse() { executeOperation( "Null-safe String Representation with Objects.requireNonNullElse(Object, Object)", () -> "The value of the 'null' object is '" + Objects.requireNonNullElse(NULL_OBJECT, "null") + "'"); executeOperation("Null-safe TimeUnit access with Objects.requireNonNullElse(Object, Object)", () -> "The value used instead of 'null' TimeUnit is '" + Objects.requireNonNullElse(NULL_TIME_UNIT, TimeUnit.SECONDS) + "'"); }
Feb 28, 2021 2:54:45 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Null-safe String Representation with Objects.requireNonNullElse(Object, Object)' completed without exception!
Feb 28, 2021 2:54:45 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Null-safe TimeUnit access with Objects.requireNonNullElse(Object, Object)' completed without exception!

Another Objects method with slightly different name (requireNonNullElseGet(T, Supplier<? extends T>)) allows the default that will be used in place of null to be specified using a Supplier. The advantage of this approach is that the operation used to compute that default value will only be executed if the object is null and the cost of executing that Supplier is NOT incurred if the specified object is null (Supplier deferred execution).

Comparing enums Safely

Although Java enums can be compared for equality using Enum.equals(Object), I prefer to use the operators == and != for comparing enums because the latter is null-safe (and arguably makes for easier reading).

The code listing and associated output that follow demonstrate that comparing enums with == is null-safe but comparing enums with .equals(Object) is NOT null-safe.

/**
 * Demonstrates that comparing a potentially {@code null} enum is
 * {@code null}-safe when the {@code ==} operator (or {@code !=}
 * operator) is used, but that potentially comparing a {@code null}
 * enum using {@link Enum#equals(Object)} results in a
 * {@link NullPointerException}.
 *
 * See also https://marxsoftware.blogspot.com/2011/07/use-to-compare-java-enums.html.
 */
public void demonstrateEnumComparisons()
{
   executeOperation(
      "Using == with enums is null Safe",
      () -> NULL_TIME_UNIT == TimeUnit.MINUTES);
   executeOperation(
      "Using .equals On null Enum is NOT null Safe",
      () -> NULL_TIME_UNIT.equals(TimeUnit.MINUTES));
}
INFO: Demonstration 'Using == with enums is null Safe' completed without exception!
Feb 28, 2021 4:30:17 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
SEVERE: Exception encountered while trying to run operation for demonstration 'Using .equals On null Enum is NOT null Safe': java.lang.NullPointerException: Cannot invoke "java.util.concurrent.TimeUnit.equals(Object)" because "dustin.examples.nullsafe.tactics.NullSafeTactics.NULL_TIME_UNIT" is null
Feb 28, 2021 4:30:17 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation

Comparing Objects Safely with Known Non-null Object on LHS of .equals(Object)

When we know that at least one of two objects being compared is definitely NOT null, we can safely compare the two objects (even if the other one may be null), by calling Object.equals(Object) against the known non-null object. There still is an element of risk here if the class which you're calling .equals(Object) against has its Object.equals(Object) method implemented in such a way that passing in a null argument leads to a NullPointerException. However, I've never encountered a JDK class or even custom class that has made that mistake (and it is a mistake in my opinion to have a Object.equals(Object) overridden method not be able to handle a supplied null and simply return false in that case instead of throwing NullPointerException). The tactic of calling .equals(Object) against the known non-null object is demonstrated in the next code listing and associated output.

/**
 * Demonstrates that comparisons against known non-{@code null} strings can be
 * {@code null}-safe as long as the known non-{@code null} string is on the left
 * side of the {@link Object#equals(Object)} method ({@link Object#equals(Object)})
 * is called on the known non-{@code null} string rather than on the unknown
 * and potential {@code null}.
 */
public void demonstrateLiteralComparisons()
{
   executeOperation(
      "Using known non-null literal on left side of .equals",
         () -> "Inspired by Actual Events".equals(NULL_STRING));
   executeOperation(
      "Using potential null variable on left side of .equals can result in NullPointerExeption",
      () -> NULL_STRING.equals("Inspired by Actual Events"));
}
Feb 28, 2021 4:46:20 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Using known non-null literal on left side of .equals' completed without exception!
Feb 28, 2021 4:46:20 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
SEVERE: Exception encountered while trying to run operation for demonstration 'Using potential null variable on left side of .equals can result in NullPointerExeption': java.lang.NullPointerException: Cannot invoke "String.equals(Object)" because "dustin.examples.nullsafe.tactics.NullSafeTactics.NULL_STRING" is null

Although it was specifically String.equals(Object) demonstrated above, this tactic applies to instances of any class as long as the class's .equals(Object) method can gracefully handle a supplied null (and I cannot recall ever encountering one that didn't handle null).

Case Insensitive Comparison of Strings Safely with Known Non-null String on LHS of .equals(Object)

Placing the known non-null object on the left side of the .equals(Object) call is a general null-safe tactic for any object of any type. For String in particular, there are times when we want a null-safe way to compare two strings without regard to the case of the characters in the strings (case insensitive comparison). The String.equalsIgnoreCase(String) method works well for this and will be a null-safe operation if we use a known non-null String on the left side of that method (method called against the known non-null String).

The code listing and associated output that follow demonstrate null-safe use of String.equalsIgnoreCase(String).

/**
 * Demonstrates that case-insensitive comparisons against known non-{@code null}
 * strings can be {@code null}-safe as long as the known non-{@code null} string
 * is on the left side of the {@link Object#equals(Object)} method
 * ({@link Object#equals(Object)}) is called on the known non-{@code null} String
 * rather than on the unknown potential {@code null}).
 */
public void demonstrateLiteralStringEqualsIgnoreCase()
{
   executeOperation(
      "String.equalsIgnoreCase(String) is null-safe with literal string on left side of method",
      () -> "Inspired by Actual Events".equalsIgnoreCase(NULL_STRING));
   executeOperation(
      "Using potential null variable of left side of .equalsIgnoreCase can result in NPE",
      () -> NULL_STRING.equalsIgnoreCase("Inspired by Actual Events"));
}
Feb 28, 2021 7:03:42 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'String.equalsIgnoreCase(String) is null-safe with literal string on left side of method' completed without exception!
Feb 28, 2021 7:03:42 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
SEVERE: Exception encountered while trying to run operation for demonstration 'Using potential null variable of left side of .equalsIgnoreCase can result in NPE': java.lang.NullPointerException: Cannot invoke "String.equalsIgnoreCase(String)" because "dustin.examples.nullsafe.tactics.NullSafeTactics.NULL_STRING" is null

These last two demonstrations used literal strings as the "known non-null" strings against which methods were called, but other strings and objects could also be used. Constants and known previously initialized fields and variables are all candidates for the objects against which the comparison methods can be called safely as long as it's known that those fields and variables can never be changed to null. For fields, this condition is only guaranteed if that field is always initialized to a non-null value with the instance and is immutable. For variables, this condition is only guaranteed if that variable is initialized to an unknown value and is final. There are many "in between" cases where it is most likely that certain objects are not null, but guarantees cannot be made. In those cases, it is less risky to explicitly check each object being compared for null before comparing them with .equals(Object) or to use the Objects.equals(Object, Object) method, which is covered next.

Safely Comparing Objects When Neither is Known to be Non-null

The Objects.equals(Object, Object) method is a highly convenient way to compare two objects for equality when we don't know whether either or both might be null. This convenience method's documentation explains its behavior and it's probably what most of u would do if writing this code ourselves, "Returns true if the arguments are equal to each other and false otherwise. Consequently, if both arguments are null, true is returned. Otherwise, if the first argument is not null, equality is determined by calling the equals method of the first argument with the second argument of this method. Otherwise, false is returned."

This is demonstrated in the next code listing and associated output.

/**
 * Demonstrates that comparisons of even potential {@code null}s is safe
 * when {@link Objects#equals(Object, Object)} is used.
 */
public void demonstrateObjectsEquals()
{
   executeOperation(
      "Using Objects.equals(Object, Object) is null-safe",
      () -> Objects.equals(NULL_OBJECT, LocalDateTime.now()));
}
Feb 28, 2021 5:11:19 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Using Objects.equals(Object, Object) is null-safe' completed without exception!

I like to use the Objects.equals(Object, Object) to quickly build my own class's .equals(Objects) methods in a null-safe manner.

The method Objects.deepEquals(Object, Object) is not demonstrated here, but it's worth pointing out its existence. The method's documentation states, "Returns true if the arguments are deeply equal to each other and false otherwise. Two null values are deeply equal. If both arguments are arrays, the algorithm in Arrays.deepEquals is used to determine equality. Otherwise, equality is determined by using the equals method of the first argument."

Null-safe Hashing

The methods Objects.hashCode(Object) (single object) and Objects.hash(Object...) (sequences of objects) can be used to safely generate hash codes for potentially null references. This is demonstrated in the following code listing and associated output.

/**
 * Demonstrates that {@link Objects#hashCode(Object)} is {@code null}-safe.
 */
public void demonstrateObjectsHashCode()
{
   executeOperation(
      "Using Objects.hashCode(Object) is null-safe",
      () -> Objects.hashCode(NULL_OBJECT));
}

/**
 * Demonstrates that {@link Objects#hash(Object...)} is {@code null}-safe.
 */
public void demonstrateObjectsHash()
{
   executeOperation(
      "Using Objects.hash(Object...) is null-safe",
      () -> Objects.hash(NULL_OBJECT, NULL_STRING, NULL_TIME_UNIT));
}
Feb 28, 2021 5:11:19 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Using Objects.hashCode(Object) is null-safe' completed without exception!
Feb 28, 2021 5:11:19 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
INFO: Demonstration 'Using Objects.hash(Object...) is null-safe' completed without exception!

These methods can be convenient for generating one's own null-safe hashCode() methods on custom classes.

It's also important to note that there is a warning in the documentation that the hash code generated by Objects.hash(Object...) for a single supplied Object is not likely to be the same value as a hash code generated for that same Object when calling the Object's own hashCode() method or when calling Objects.hashCode(Object) on that Object.

Elegantly Handling Useful NullPointerExceptions

The tactics described and demonstrated so far were primarily aimed at avoiding NullPointerException in situations where we fully anticipated a reference being null but that presence of a null is in no way exceptional and so we don't want any exception (including NullPointerException) to be thrown. The remainder of the descriptions and examples in this post will focus instead of situations where we want to handle a truly unexpected (and therefore exceptional) null as elegantly as possible. In many of these cases, we do NOT want to preclude the NullPointerException from being thrown because its occurrence will communicate to us some unexpected condition (often bad data or faulty upstream code logic) that we need to address.

The improved NullPointerException messages have made unexpected NullPointerExceptions far more meaningful. However, we can often take a few additional tactics to further improve the usefulness of the NullPointerException that is thrown when we run into an unanticipated null. These tactics include adding our own custom context details to the exception and throwing the exception early so that a bunch of logic is not performed needlessly that may also need to be reverted.

Controlling When and What Related to Unexpected null

I like to use Objects.requireNonNull(T, String) at the beginning of my public methods that accept arguments which will lead to a NullPointerException if a passed-in argument is null. While a NullPointerException is thrown in either case (either implicitly when an attempt to deference the null or when Objects.requireNonNull(T, String) is called), I like the ability to be able to specify a string with details and context about what's happing when the null is unexpectedly encountered.

The Objects.requireNonNull(T) method does not allow one to specify a string with additional context, but it is still a useful guard method. Both of these methods allow the developer to take control of when a NullPointerException will be thrown for the unexpected null and this control allows the developer to preclude unnecessary logic from being performed. We'd rather not waste time/cycles on something that is going to lead to that exception anyway and we can often choose places in the code where it's cleaner to check for null and throw the exception to avoid having to "undo" pr "revert" logic that has been performed.

The following code listing and associated output demonstrate both of these methods in action.

/**
 * Demonstrates using {@link Objects#requireNonNull(Object)} and
 * {@link Objects#requireNonNull(Object, String)} to take control of
 * when an {@link NullPointerException} is thrown. The method accepting
 * a {@link String} also allows control of the context that is provided
 * in the exception message.
 *
 * It is not demonstrated here, but a similar method is
 * {@link Objects#requireNonNull(Object, Supplier)} that allows a
 * {@link Supplier} to be used to provide the message for when an
 * unexpected {@code null} is encountered.
 */
public void demonstrateObjectsRequiresNonNullMethods()
{
   executeOperation(
      "Using Objects.requireNonNull(T)",
      () -> Objects.requireNonNull(NULL_OBJECT));

   executeOperation(
      "Using Objects.requireNonNull(T, String)",
      () -> Objects.requireNonNull(NULL_OBJECT, "Cannot perform logic on supplied null object."));
}
Feb 28, 2021 5:59:42 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
SEVERE: Exception encountered while trying to run operation for demonstration 'Using Objects.requireNonNull(T)': java.lang.NullPointerException
Feb 28, 2021 5:59:42 PM dustin.examples.nullsafe.tactics.NullSafeTactics executeOperation
SEVERE: Exception encountered while trying to run operation for demonstration 'Using Objects.requireNonNull(T, String)': java.lang.NullPointerException: Cannot perform logic on supplied null object.

The output shows us that the method that accepted a String was able to provide that additional context in its message, which can be very useful when figuring out why the unexpected null occurred.

I don't demonstrate it here, but it's worth noting that another overloaded version of this method (Objects.requireNonNull(T, Supplier<String>)) allows a developer to use a Supplier to supply a custom NullPointerException for complete control over the exception that is thrown. The use of the Supplier and its deferred execution means that this exception generation will only be performed when the object is null. One might choose to implement this Supplier as a relatively expensive operation checking various data sources and/or instance values and would not need to worry about incurring that cost unless the unexpected null was encountered.

Other Null-Handling Tactics

There are other tactics that can be used to either avoid unnecessary NullPointerExceptions or to make NullPointerExceptions due to unexpected null more useful. These include explicit checking for null in conditionals and use of Optional.

Conclusion

This post has discussed and demonstrated tactics for using standard JDK APIs to appropriately avoid unnecessary NullPointerExceptions and to more effectively use NullPointerExceptions to indicate unexpected nulls. There are several simple tactics to ensure that expected nulls do not lead to NullPointerException. There are also tactics available to control when a NullPointerException is thrown and what details are provided in it when an unexpected null is encountered.