Praise for Java 9 Modularity Modularity represents a truly deep and fundamental change to the way that Java applications are built and deployed. Java 9 Modularity is the guide you and your applications need to make the most of the potential of this new and uncharted world. —Ben Evans, Java Champion and Cofounder, jClarity Modularization is hard. Luckily I’ve been able to use Paul and Sander’s book as my guide for writing my Java 9 tutorials, talks, and converting jClarity’s applications to use Java’s new modular system. I’m buying a copy for all the engineering team at jClarity, it’s that good! —Martijn Verburg, CEO, jClarity and Sun/Oracle Java Champion This book delivers the essential practical knowledge you need to create modular applications in Java 9. It’s a must read for any developer or architect wanting to adopt one of the most significant features the JDK has seen in many years. —Simon Maple, Director of Developer Relations, ZeroTurnaround Java 9 Modularity Patterns and Practices for Developing Maintainable Applications Sander Mak and Paul Bakker Java 9 Modularity by Sander Mak and Paul Bakker Copyright © 2017 Sander Mak and Paul Bakker. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://oreilly.com/safari). For more information, contact our corporate/institutional sales department: 800-998- 9938 or [email protected]. Editors: Nan Barber and Brian Foster Production Editor: Nicholas Adams Copyeditor: Sharon Wilkey Proofreader: Charles Roumeliotis Indexer: Ellen Troutman-Zaig Interior Designer: David Futato Cover Designer: Karen Montgomery Illustrator: Rebecca Demarest September 2017: First Edition Revision History for the First Edition 2017-09-05: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781491954164 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Java 9 Modularity, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. While the publisher and the authors have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights. 978-1-491-95416-4 [LSI] Foreword What is modularity in Java? To some, it’s a principle for development: programming to interfaces and hiding the details of implementations. This is the school of encapsulation. To others, it’s about leaning hard on class loaders to provide dynamic execution environments. This is the school of isolation. To still others, it’s about artifacts, repositories, and tooling. This is the school of configuration. Individually, these perspectives are valid, but they feel like pieces of a larger story that’s not quite clear. If a developer knows that some portion of their code is for internal use only, why can’t they hide a package as easily as hiding a class or a field? If code can be compiled and run only in the presence of its dependencies, why don’t those dependencies flow smoothly from compilation to packaging to installation to execution? If tools work only when presented with pristine self-describing artifacts, how can anyone reuse older libraries that are just plain JAR files? Java 9 offers a coherent story for modularity by introducing modules as a first-class feature of the Java platform. A module is a set of packages designed for reuse. This simple concept has a surprisingly powerful impact on how code is developed, deployed, and run. The longstanding mechanisms for promoting and controlling reuse in Java—interfaces, access control, JAR files, class loaders, dynamic linking— all work better when packages are placed into modules. First, modules clarify the structure of a program in a way that other mechanisms cannot. Many developers will be surprised that their code is not as well structured as they thought. For example, a codebase spread across multiple JAR files has a good chance of cycles between classes in different JAR files, but cycles between classes in different modules are forbidden. One of the motivations for investing in the modularization of a codebase is the knowledge that, once complete, there won’t be any backsliding into the ball of mud that cyclic dependencies allow. Developing with modules also leads to programming with services, which reduce coupling and increase abstraction even further. Second, modules engender a sense of responsibility for code in a way that other mechanisms cannot. A developer who exports packages from a module is making a commitment to a stable API, and even the name of the module itself is part of the API. A developer who bundles too much functionality into a single module will cause that module to drag in a large number of dependencies that are irrelevant for any single task; anyone who reuses the module will realize its sprawling nature even if its internals are hidden. Developing with modules encourages every developer to think about the stability and cohesiveness of their code. Most people are familiar with the tablecloth trick, where the cloth is whipped off the table without upsetting the plates and cups. For those of us who worked on Java 9, designing a module system that could slide into the Java Virtual Machine underneath the millions of classes developed since the 1990s felt rather like performing the trick in reverse. It turned out that modularizing the JDK caused the trick to fail, because some well-known libraries derived their power from trying to ignore the very encapsulation that the module system applied to the JDK’s modules. This tension in the design of Java 9 had no easy academic answers. In the end, a strong cycle of feedback from the community led to the module system offering developers a variety of levers and dials, so that modularized platform code can enjoy truly strong encapsulation while modularized application code can enjoy “strong enough” encapsulation. Over time, we think the bold choices made in modularizing the JDK will make all code more reliable. A module system works best when it works for everyone. The more developers who create modules today, the more developers who will create modules tomorrow. But what about developers who have not created their modules yet? It is no exaggeration to say that Java 9 is just as concerned about the code that is not in modules as about the code that is. The only developer who should modularize a codebase is its author, so until that happens, the module system has to provide a way for code in modules to reach out to code not in modules. This led to the design of automatic modules which are so well explained in this book. Sander and Paul are expert practitioners of Java and trusted guides to the Java 9 ecosystem. They were on the front lines of Java 9’s development, and in the vanguard of efforts to migrate popular open source libraries. Java 9 Modularity is the handbook for everyone interested in the core principles and best practices of modularity in Java: application developers looking to create maintainable components; library developers looking for advice on migration and reflection; and framework developers wishing to exploit the module system’s advanced features. I hope this book will help you to create Java programs whose structure lets them stand the test of time. Alex Buckley Java Platform Group, Oracle Santa Clara, July 2017 Preface Java 9 introduces a module system to the platform. This is a major leap, marking the start of a new era for modular software development on the Java platform. We’re very excited about these changes, and we hope you are too after reading this book. You’ll be ready to make the best use of the module system before you know it. Who Should Read This Book This book is for Java developers who want to improve the design and structure of their applications. The Java module system improves the way we can design and build Java applications. Even if you’re not going to use modules right away, understanding the modularization of the JDK itself is an important first step. After you acquaint yourself with modules in the first part of the book, we expect you to also really appreciate the migration chapters that follow. Moving existing code to Java 9 and the module system will become an increasingly common task. This book is by no means a general introduction to Java. We assume you have experience writing relatively large Java applications in a team setting. That’s where modularity becomes more and more important. As an experienced Java developer, you will recognize the problems caused by the classpath, helping you appreciate the module system and its features. There are many other changes in Java 9 besides the module system. This book, however, focuses on the module system and related features. Where appropriate, other Java 9 features are discussed in the context of the module system. Why We Wrote This Book We have been Java users since the early days of Java, when applets still were hot stuff. We’ve used and enjoyed many other platforms and languages over the years, but Java still remains our primary tool. When it comes to building maintainable software, modularity is a key principle. Pursuing modular application development has become somewhat of a passion for us, after spending a lot of energy building modular software over the years. We’ve used technology such as OSGi extensively to achieve this, without support in the Java platform itself. We’ve also learned from tools outside the Java space, such as module systems for JavaScript. When it became clear that Java 9 would feature the long-awaited module system, we decided we didn’t want to just use this feature, but also help with onboarding other developers. Maybe you have heard of Project Jigsaw at some point in the past decade. Project Jigsaw prototyped many possible implementations of a Java module system over the course of many years. A module system for Java has been on and off the table several times. Both Java 7 and 8 were originally going to include the results of Project Jigsaw. With Java 9, this long period of experimentation culminates into an official module system implementation. Many changes have occurred in the scope and functionality of the various module system prototypes over the years. Even when you’ve been following this process closely, it’s difficult to see what the final Java 9 module system really entails. Through this book, we want to provide a definitive overview of the module system. And, more important, what it can do for the design and architecture of your applications. Navigating This Book The book is split into three parts: 1. Introduction to the Java Module System 2. Migration 3. Modular Development Tooling The first part teaches you how to use the module system. Starting with the modular JDK itself, it then goes into creating your own modules. Next we discuss services, which enable decoupling of modules. The first part ends with a discussion of modularity patterns, and how you use modules in a way to maximize maintainability and extensibility. The second part of the book is about migration. You most likely have existing Java code, probably using Java libraries that were not designed for the module system. In this part of the book, you will learn how to migrate existing code to modules, and how to use existing libraries that are not modules yet. If you are the author or maintainer of a library, there is a chapter specifically about adding module support to libraries. The third and last part of the book is about tooling. In this part, you will learn about the current state of IDEs and build tools. You will also learn how to test modules, because modules give some new challenges but also opportunities when it comes to (unit) testing. Finally, you will also learn about linking, another exciting feature of the module system. It enables the creation of highly optimized custom runtime images, changing the way you can ship Java applications by virtue of modules. The book is designed to be read from cover to cover, but we kept in mind that this is not an option for every reader. We recommend to at least go over the first four chapters in detail. This will set you up with the basic knowledge to make good use of the rest of the book. If you are really short on time and have existing code to migrate, you can skip to the second part of the book after that. Once you’re ready for it, you should be able to come back to the more advanced chapters. Using Code Examples The book contains many code examples. All code examples are available on GitHub at https://github.com/java9-modularity/examples. In this repository, the code examples are organized by chapter. Throughout the book we refer to specific code examples as follows: ➥ chapter3/helloworld. This means the example can be found in https://github.com/java9-modularity/examples/chapter3/helloworld. We highly recommend having the code available when going through the book, because longer code sections just read better in a code editor. We also recommend playing with the code yourself—for example, to reproduce errors that we discuss in the book. Learning by doing beats just reading the words. Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Used for program listings, as well as within paragraphs to refer to program