What's New overhaul

Author: jhoeller

src/asciidoc/index.adoc

@@ -752,22 +752,22 @@ the exact version and feature set of the container.
 
 [[new-in-4.0]]
 == New Features and Enhancements in Spring Framework 4.0
-The Spring Framework was first released in 2004, since then there have been only a
-few major revisions: Spring 2.0 provided cleaner XML support and improved AOP; Spring 2.5
-embraced annotation-driven configuration; Spring 3.0 added Java 5 features, such as
-generics and java-based `@Configuration`.
+The Spring Framework was first released in 2004; since then there have been significant
+major revisions: Spring 2.0 provided XML namespaces and AspectJ support; Spring 2.5
+embraced annotation-driven configuration; Spring 3.0 introduced a strong Java 5+ foundation
+across the framework codebase, and features such as the Java-based `@Configuration` model.
 
 Version 4.0 is the latest major release of the Spring Framework and the first to fully
 support Java 8 features. You can still use Spring with older versions of Java, however,
 the minimum requirement has now been raised to Java SE 6. We have also taken the
-opportunity of a major release to remove many deprecated classes and methods from the
-previous version.
+opportunity of a major release to remove many deprecated classes and methods.
 
 A https://github.com/spring-projects/spring-framework/wiki/Migrating-from-earlier-versions-of-the-spring-framework[migration guide for upgrading to Spring 4.0]
 is available on the https://github.com/spring-projects/spring-framework/wiki[Spring Framework GitHub Wiki].
 
 
 
+
 === Improved Getting Started Experience
 The new http://spring.io[spring.io] website provides a whole series of
 http://spring.io/guides["Getting Started"] guides to help you learn Spring. You
@@ -783,66 +783,106 @@ Framework release.
 
 
 === Removed Deprecated Packages and Methods
-All deprecated packages, and many deprecated classes, methods, and fields have been
-removed with version 4.0. If you are upgrading from a previous release of Spring, you
-should ensure that you have fixed any deprecated calls that you were making.
+All deprecated packages, and many deprecated classes and methods have been removed with
+version 4.0. If you are upgrading from a previous release of Spring, you should ensure
+that you have fixed any deprecated calls that you were making to outdated APIs.
 
 For a complete set of changes, check out the
 http://docs.spring.io/spring-framework/docs/3.2.4.RELEASE_to_4.0.0.RELEASE/[API
 Differences Report].
 
+Note that optional third-party dependencies have been raised to a 2010/2011 minimum
+(i.e. Spring 4 generally only supports versions released in late 2010 or later now):
+notably, Hibernate 3.6+, EhCache 2.1+, Quartz 1.8+, Groovy 1.8+, and Joda-Time 2.0+.
+As an exception to the rule, Spring 4 requires the recent Hibernate Validator 4.3+,
+and support for Jackson has been focused on 2.0+ now (with Jackson 1.8/1.9 support
+retained for the time being where Spring 3.2 had it; now just in deprecated form).
+
 
 
 
-=== Java 8
+=== Java 8 (as well as 6 and 7)
 Spring Framework 4.0 provides support for several Java 8 features. You can make use of
 __lambda expressions__ and __method references__ with Spring's callback interfaces. There
 is first class support for `java.time` (http://jcp.org/en/jsr/detail?id=310[JSR-310]) and
 several existing annotations have been retrofitted as `@Repeatable`. You can also use
 Java 8's parameter name discovery as an alternative to compiling your code with debug
 information enabled.
 
-Spring remains compatible with older versions of Java, 6.0 and above are fully
-supported.
+Spring remains compatible with older versions of Java and the JDK: Concretely, Java SE 6
+(specifically, a minimum level equivalent to JDK 6 update 10, as released in late 2008)
+and above are still fully supported. However, for newly started development projects
+based on Spring 4, we recommend the use of Java 7 or 8.
 
+Note that the Java 8 bytecode level (-target 1.8, as required by -source 1.8) is only
+fully supported as of Spring Framework 4.0. In particular, Spring 3.2 based applications
+need to be compiled with a maximum of Java 7 as the target, even if they happen to be
+deployed onto a Java 8 runtime. Please upgrade to Spring 4 for Java 8 based applications.
 
 
 
-=== Java EE 6
-Java EE version 6 or above is now considered the baseline for Spring Framework 4.0. With
+
+=== Java EE 6 and 7
+Java EE version 6 or above is now considered the baseline for Spring Framework 4, with
 the JPA 2.0 and Servlet 3.0 specifications being of particular relevance. In order to
-remain compatible with Google App Engine, it is possible to deploy a Spring application
-into a Servlet 2.5 environment, however, Servlet 3.0+ is recommended when at all possible.
+remain compatible with Google App Engine and older application servers, it is possible
+to deploy a Spring application into a Servlet 2.5 environment; however, Servlet 3.0+
+is recommended when at all possible.
 
-If you are a WebSphere 7 user, be sure install the JPA 2.0 feature pack.
+Note: If you are a WebSphere 7 user, be sure install the JPA 2.0 feature pack. On
+WebLogic 10.3.4 or higher, install the JPA 2.0 patch that comes with it. This turns
+both of those server generations into Spring 4 compatible deployment environments.
 
+On a more forward-looking note, Spring Framework 4.0 supports the Java EE 7 level of
+applicable specifications now: in particular, JMS 2.0, JTA 1.2, JPA 2.1, Bean Validation
+1.1, and JSR-236 Concurrency Utilities. As usual, this support focuses on individual
+use of those specifications, e.g. on Tomcat or in standalone environments. However,
+it works equally well when a Spring application is being deployed to a Java EE 7 server.
 
+Note that Hibernate 4.3 is a JPA 2.1 provider and therefore only supported as of
+Spring Framework 4.0. The same applies to Hibernate Validator 5.0 as a Bean Validation
+1.1 provider. Neither of the two are officially supported with Spring Framework 3.2.
 
 
-=== WebSocket, SockJS, and STOMP Messaging
-A new `spring-websocket` module provides comprehensive support for WebSocket-based,
-two-way communication between client and server in web applications. It is compatible with
-http://jcp.org/en/jsr/detail?id=356[JSR-356], the Java WebSocket API, and in addition
-provides SockJS-based fallback options (i.e. WebSocket emulation) for use in browsers
-that don't yet support the WebSocket protocol (e.g. IE < 10).
 
-A new `spring-messaging` module adds support for STOMP as the WebSocket sub-protocol
-to use in applications along with an annotation programming model for routing and
-processing STOMP messages from WebSocket clients. As a result an `@Controller`
-can now contain both `@RequestMapping` and `@MessageMapping` methods for handling
-HTTP requests and messages from WebSocket-connected clients. The new `spring-messaging`
-module also contains key abstractions from the
-http://projects.spring.io/spring-integration/[Spring Integration] project such as
-`Message`, `MessageChannel`, `MessageHandler` and others to serve as
-a foundation for messaging applications.
 
-For more details including a more thorough introduction see the <<websocket>> section.
+=== Groovy Bean Definition DSL
+With Spring Framework 4.0 it is now possible to define external bean configuration using
+a Groovy DSL. This is similar in concept to using XML bean definitions, but allows for
+a more concise syntax. Using Groovy also allows you to easily embed bean definitions
+directly in your bootstrap code. For example:
+
+[source,groovy,indent=0]
+[subs="verbatim,quotes"]
+----
+	def reader = new GroovyBeanDefinitionReader(myApplicationContext)
+	reader.beans {
+		dataSource(BasicDataSource) {
+			driverClassName = "org.hsqldb.jdbcDriver"
+			url = "jdbc:hsqldb:mem:grailsDB"
+			username = "sa"
+			password = ""
+			settings = [mynew:"setting"]
+		}
+		sessionFactory(SessionFactory) {
+			dataSource = dataSource
+		}
+		myService(MyService) {
+			nestedBean = { AnotherBean bean ->
+				dataSource = dataSource
+			}
+		}
+	}
+----
+
+For more information consult the `GroovyBeanDefinitionReader`
+{javadoc-baseurl}/org/springframework/beans/factory/groovy/GroovyBeanDefinitionReader.html[Javadoc].
 
 
 
 
 === Core Container Improvements
-There have been several general improvements to the core IoC container:
+There have been several general improvements to the core container:
 
 * Spring now treats <<beans-generics-as-qualifiers,__generic types__ as a form of
   __qualifier__>> when injecting Beans. For example, if you are using a Spring Data
@@ -853,22 +893,23 @@ There have been several general improvements to the core IoC container:
 * Beans can now be `Ordered` when they are <<beans-autowired-annotation,autowired into
   lists and arrays>>. Both the `@Ordered` annotation and `Ordered` interface are
   supported.
-* A generalized model for <<beans-java-conditional,conditionally filtering beans>> has
-  been added via the `@Conditional` annotation. This is similar to `@Profile` but allow
-  user-defined strategies to be developed.
-* <<aop-pfb-proxy-types,CGLIB-based proxy classes>> no longer require a default
-  constructor. Support is provided via the http://code.google.com/p/objenesis/[objenesis]
-  library which is repackaged __inline__ and distributed as part of the Spring Framework.
 * The `@Lazy` annotation can now be used on injection points, as well as `@Bean`
   definitions.
 * The <<beans-java-bean-description,`@Description` annotation has been added>> for
   developers using Java-based configuration.
-* It is now possible to specify a time zone with the `@Scheduled` annotation.
+* A generalized model for <<beans-java-conditional,conditionally filtering beans>> has
+  been added via the `@Conditional` annotation. This is similar to `@Profile` but allows
+  for user-defined strategies to be developed.
+* <<aop-pfb-proxy-types,CGLIB-based proxy classes>> no longer require a default
+  constructor. Support is provided via the http://code.google.com/p/objenesis/[objenesis]
+  library which is repackaged __inline__ and distributed as part of the Spring Framework.
+  With this strategy, no constructor at all is being invoked for proxy instances anymore.
+* There is managed time zone support across the framework now, e.g. on `LocaleContext`.
 
 
 
 
-=== Web Improvements
+=== General Web Improvements
 Deployment to Servlet 2.5 servers remains an option, but Spring Framework 4.0 is now
 focused primarily on Servlet 3.0+ environments. If you are using the
 <<spring-mvc-test-framework,Spring MVC Test Framework>> you
@@ -886,37 +927,28 @@ have been made to Spring's Web modules:
   Spring MVC applications.
 
 
-=== Groovy DSL Support
-With Spring Framework 4.0 it is now possible to define external bean configuration using
-a Groovy DSL. This is similar in concept to using XML bean definitions, but allows for
-a much more concise syntax. Using Groovy also allows you to easily embed bean definitions
-directly in your code. For example:
 
-[source,groovy,indent=0]
-[subs="verbatim,quotes"]
-----
-	def reader = new GroovyBeanDefinitionReader(myApplicationContext)
-	reader.beans {
-		dataSource(BasicDataSource) {
-			driverClassName = "org.hsqldb.jdbcDriver"
-			url = "jdbc:hsqldb:mem:grailsDB"
-			username = "sa"
-			password = ""
-			settings = [mynew:"setting"]
-		}
-		sessionFactory(SessionFactory) {
-			dataSource = dataSource
-		}
-		myService(MyService) {
-			nestedBean = { AnotherBean bean ->
-				dataSource = dataSource
-			}
-		}
-	}
-----
 
-For more information consult the `GroovyBeanDefinitionReader`
-{javadoc-baseurl}/org/springframework/beans/factory/groovy/GroovyBeanDefinitionReader.html[Javadoc].
+=== WebSocket, SockJS, and STOMP Messaging
+A new `spring-websocket` module provides comprehensive support for WebSocket-based,
+two-way communication between client and server in web applications. It is compatible with
+http://jcp.org/en/jsr/detail?id=356[JSR-356], the Java WebSocket API, and in addition
+provides SockJS-based fallback options (i.e. WebSocket emulation) for use in browsers
+that don't yet support the WebSocket protocol (e.g. IE < 10).
+
+A new `spring-messaging` module adds support for STOMP as the WebSocket sub-protocol
+to use in applications along with an annotation programming model for routing and
+processing STOMP messages from WebSocket clients. As a result an `@Controller`
+can now contain both `@RequestMapping` and `@MessageMapping` methods for handling
+HTTP requests and messages from WebSocket-connected clients. The new `spring-messaging`
+module also contains key abstractions from the
+http://projects.spring.io/spring-integration/[Spring Integration] project such as
+`Message`, `MessageChannel`, `MessageHandler` and others to serve as
+a foundation for messaging applications.
+
+For more details including a more thorough introduction, see the <<websocket>> section.
+
+
 
 
 === Testing Improvements
@@ -942,6 +974,8 @@ Framework 4.0 introduces several new features for use in unit and integration te
 
 
 
+
+
 [[spring-core]]
 = Core Technologies
 [partintro]
@@ -36629,7 +36663,7 @@ WebSocket clients or to a specific user.
 [[websocket-server]]
 === WebSocket Server
 The Spring Framework provides a WebSocket API designed to adapt to various WebSocket engines.
-For example it runs on JSR-356 runtimes such as Tomcat (7.0.47+) and Glassfish (4.0+) but
+For example it runs on JSR-356 runtimes such as Tomcat (7.0.47+) and GlassFish (4.0+) but
 can also adapt to other WebSocket runtimes such as the Jetty (9.0+) native WebSocket support.
 
 [NOTE]
@@ -36818,7 +36852,7 @@ requests -- such as Spring MVC's `DispatcherServlet`.
 This is a significant limitation of JSR-356 that Spring's WebSocket support
 addresses by providing a server-specific `RequestUpgradeStrategy` even when
 running in a JSR-356 runtime. At present such support is available on
-Tomcat 7.0.47+, Jetty 9.0+, and Glassfish 4.0+. Additional support will be
+Tomcat 7.0.47+, Jetty 9.0+, and GlassFish 4.0+. Additional support will be
 added as more WebSocket runtimes become available.
 
 [NOTE]
@@ -45058,12 +45092,14 @@ below).
 [NOTE]
 ====
 The default key generation strategy changed with the release of Spring 4.0. Earlier
-versions of Spring used a key generation strategy that only considered the `hashCode()`
-of parameters and not `equals()`, this often caused unexpected key collisions (see
-https://jira.springsource.org/browse/SPR-10237[SPR-10237] for background).
-
-If you want to use the previous key generator, you can use the
-`org.springframework.cache.interceptor.DefaultKeyGenerator` class.
+versions of Spring used a key generation strategy that, for multiple key parameters,
+only considered the `hashCode()` of parameters and not `equals()`; this could cause
+unexpected key collisions (see https://jira.springsource.org/browse/SPR-10237[SPR-10237]
+for background). The new 'SimpleKeyGenerator' uses a compound key for such scenarios.
+
+If you want to keep using the previous key strategy, you can configure the deprecated
+`org.springframework.cache.interceptor.DefaultKeyGenerator` class or create a custom
+hash-based 'KeyGenerator' implementation.
 ====