Overview with explicit JDK 9 (Jigsaw) and Java EE 8 references

Author: jhoeller

src/docs/asciidoc/appendix.adoc

@@ -14,7 +14,7 @@ link:{wiki-spring-framework}/++What's-New-in-the-Spring-Framework++[Wiki page].
 
 
 [[migration-4.x]]
-== Migrating to Spring Framework 4.x
+== Migrating to Spring Framework 4.3 / 5.0
 Migration guides for upgrading from previous releases of the Spring Framework are now provided as a
 {wiki-spring-framework}/Migrating-from-earlier-versions-of-the-spring-framework[Wiki page].
 

src/docs/asciidoc/data-access.adoc

@@ -5098,10 +5098,10 @@ chapter will then cover the other ORM technologies, showing briefer examples the
 
 [NOTE]
 ====
-As of Spring 5.0, Spring requires Hibernate ORM 4.3 or later for JPA support and even
-Hibernate ORM 5.0+ for programming against the native Hibernate Session API. Note that
-the Hibernate team does not maintain any versions prior to 5.0 anymore and is likely
-to focus on 5.2+ exclusively soon.
+As of Spring Framework 5.0, Spring requires Hibernate ORM 4.3 or later for JPA support
+and even Hibernate ORM 5.0+ for programming against the native Hibernate Session API.
+Note that the Hibernate team does not maintain any versions prior to 5.0 anymore and
+is likely to focus on 5.2+ exclusively soon.
 ====
 
 

src/docs/asciidoc/overview.adoc

@@ -4,10 +4,12 @@
 = Spring Framework Overview
 
 Spring makes it easy to create Java enterprise applications. It provides everything you
-need beyond the Java language itself. It also provides extensions and support for
-applications created in Groovy and Kotlin.
+need to embrace the Java language in an enterprise environment, with support for Groovy
+and Kotlin as alternative languages on the JVM, and with the flexibility to create many
+kinds of architectures depending on an application's needs. As of Spring Framework 5.0,
+Spring requires JDK 8+ (Java SE 8+) and provides out-of-the-box support for JDK 9 already.
 
-Spring supports a wide range of application scenarios.  In a large enterprise, applications
+Spring supports a wide range of application scenarios. In a large enterprise, applications
 often exist for a long time and have to run on a JDK and application server whose upgrade
 cycle is beyond developer control. Others may run as a single jar with the server embedded,
 possibly in a cloud environment. Yet others may be standalone applications (such as batch
@@ -19,45 +21,59 @@ evolve over a very long time.
 
 == What We Mean by "Spring"
 
-The term, "Spring," means different things in different contexts. It can be used to refer to
+The term "Spring" means different things in different contexts. It can be used to refer to
 the Spring Framework project itself, which is where it all started. Over time, other Spring
-projects have been built on top of the Spring Framework. Most often, when people say,
-“Spring,” they mean the entire family of projects. This reference documentation focuses on
-the Spring Framework.
+projects have been built on top of the Spring Framework. Most often, when people say
+"Spring", they mean the entire family of projects. This reference documentation focuses on
+the foundation: the Spring Framework itself.
 
 The Spring Framework is divided into modules. Applications can choose which modules they need.
 At the heart are the modules of the core container, including a configuration model and a
 dependency injection mechanism. Beyond that, the Spring Framework provides foundational
 support for different application architectures, including messaging, transactional data and
-persistence, and web. It also includes the servlet-based Spring MVC web framework and, in
+persistence, and web. It also includes the Servlet-based Spring MVC web framework and, in
 parallel, the Spring WebFlux reactive web framework.
 
+A note about modules: Spring's framework jars allow for deployment to JDK 9's module path
+("Jigsaw"). For use in Jigsaw-enabled applications, the Spring Framework 5 jars come with
+"Automatic-Module-Name" manifest entries which define stable language-level module names
+("spring.core", "spring.context" etc) independent from jar artifact names (the jars follow
+the same naming pattern with "-" instead of ".", e.g. "spring-core" and "spring-context").
+Of course, Spring's framework jars keep working fine on the classpath on both JDK 8 and 9.
+
 == History of Spring and the Spring Framework
 
 Spring came into being in 2003 as a response to the complexity of the early
 https://en.wikipedia.org/wiki/Java_Platform,_Enterprise_Edition[J2EE] specifications.
 While some consider Java EE and Spring to be in competition, Spring is, in fact, complementary
-to Java EE.  Spring does not support every Java EE specification. Rather, it integrates with
-a carefully selected subset of the most widely used Java EE specifications:
+to Java EE. The Spring programming model does not embrace the Java EE platform specification;
+rather, it integrates with carefully selected individual specifications from the EE umbrella:
 
-* JPA (https://jcp.org/en/jsr/detail?id=338[JSR 338])
-* JMS (https://jcp.org/en/jsr/detail?id=914[JSR 914])
 * Servlet API (https://jcp.org/en/jsr/detail?id=340[JSR 340])
-* WebSockets (https://www.jcp.org/en/jsr/detail?id=356[JSR 356])
+* WebSocket API (https://www.jcp.org/en/jsr/detail?id=356[JSR 356])
+* Concurrency Utilities (https://www.jcp.org/en/jsr/detail?id=236[JSR 236])
 * JSON Binding API (https://jcp.org/en/jsr/detail?id=367[JSR 367])
 * Bean Validation (https://jcp.org/en/jsr/detail?id=303[JSR 303])
+* JPA (https://jcp.org/en/jsr/detail?id=338[JSR 338])
+* JMS (https://jcp.org/en/jsr/detail?id=914[JSR 914])
+* as well as JTA/JCA setups for transaction coordination, if necessary.
 
 The Spring Framework also supports the Dependency Injection
 (https://www.jcp.org/en/jsr/detail?id=330[JSR 330]) and Common Annotations
 (https://jcp.org/en/jsr/detail?id=250[JSR 250]) specifications, which application developers
-can choose to use instead of the same mechanisms provided by the Spring Framework.
+may choose to use instead of the Spring-specific mechanisms provided by the Spring Framework.
+
+As of Spring Framework 5.0, Spring requires the Java EE 7 level (e.g. Servlet 3.1+, JPA 2.1+)
+as a minimum - while at the same time providing out-of-the-box integration with newer APIs
+at the Java EE 8 level (e.g. Servlet 4.0, JSON Binding API) when encountered at runtime.
+This keeps Spring fully compatible with e.g. Tomcat 8 and 9, WebSphere 9, and JBoss EAP 7.
 
 Over time, the role of Java EE in application development has evolved. In the early days of
 Java EE and Spring, applications were created to be deployed to an application server.
 Today, with the help of Spring Boot, applications are created in a devops- and
-cloud-friendly way, with the servlet container embedded and trivial to change.
-As of Spring 5, a WebFlux application does not even use the Servlet API directly and can
-run on servers (such as Netty) that are not servlet containers.
+cloud-friendly way, with the Servlet container embedded and trivial to change.
+As of Spring Framework 5, a WebFlux application does not even use the Servlet API directly
+and can run on servers (such as Netty) that are not Servlet containers.
 
 Spring continues to innovate and to evolve. Beyond the Spring Framework, there are other
 projects, such as Spring Boot, Spring Security, Spring Data, Spring Cloud, Spring Batch,