Let's assume you are done with the steps in the previous chapter and your legacy code now complies or runs in Java 9. You are ready for the next step--to migrate your code to use Java 9 modules! What does that look like?

Here's a very high-level picture that shows the different elements of a typical pre-Java 9 application running on a Java 9 platform:

You can break a typical application down into three distinct layers. At the very top layer are the application classes and jars. Typical applications have a combination of application classes and jars along with any internal libraries, such as shared utility components. All of these are application specific. Since the application is yet to be migrated to Java 9, this layer consists of classes and jars in the classpath.

The second layer denotes any frameworks that the application might be using. It's very rare to find Java applications these days that do not use an application framework of some sort. Frameworks such as Spring, Vaadin, JSF, and Hibernate are very commonly used. These are typically bundled into the application as .jar files, either downloaded manually or through a dependency management utility such as Maven or Gradle. Will the libraries be in the classpath or the module path? It depends on the library, and if the authors have migrated it to Java 9. If the libraries are already migrated, all you need to do is simply add them to the module path! However, for the sake of this chapter, let's assume that the libraries are still not migrated, so that you know how to tackle the more complex scenario.

The third layer is the underlying Java Platform that powers it all. This, as we've seen in this book, is a fully modularized platform as of Java 9.

Since we are assuming that none of the application code or the libraries are Java 9 modules, they are primarily running in the class path, and the module path is completely empty. This is just the way we left our code at the end of the previous chapter. Here's the before picture:

The goal is to create modules and move everything from the classpath into the module path. Once we are done, the classpath will be empty and everything that the application needs will run from the module path. Here's the ideal after picture:

Notice that in the after picture, we aren't even using the classpath anymore. All the code and binaries we need are now converted to modules and made available in the module path. Thus, in an ideal world, there is no need to even pass the classpath argument! Also, notice that I have intentionally changed the representation of modules to random sizes. This is to highlight that there might not be a one-to-one mapping between the JARs and classes in the classpath to the converted modules. You might break a single JAR in your Java 8 application into multiple modules in Java 9 or merge multiple JARs into a single module.

Now that we have an idea about what the end goal is, let's look at the migration strategy.