Upgrading from 17 to 21

Java 21 Course · lesson 14 of 15 · 4 min read

A practical order of work, and the one change that gives most of the benefit.

Open this lesson in the learning hub

Key points

  • Start by compiling and running on 21 with no source changes - 17 to 21 is a mild jump.
  • Fix agent and build-plugin compatibility first; that is where most failures actually appear.
  • Then adopt virtual threads at the edges - the request executor - not deep inside library code.
  • Replace synchronized around blocking calls with ReentrantLock before you turn them on.
  • Leave preview features out of production; adopt the finalised ones - patterns and sequenced collections.

Upgrade the runtime first and adopt features second - separating them makes failures diagnosable.

What 21 deprecated and restricted Virtual threads in a real service

This is a reading copy. The full lesson — with the visual explainer, the interactive lab and a Run button for the code — lives in the Java 21 Course course, and every lesson in it is listed on the Java 21 Course contents page.