Explicit notes for load-time weaving on Tomcat 7.0.63+ and WildFly 9

Issue: SPR-13210

Author: jhoeller

spring-context/src/main/java/org/springframework/instrument/classloading/jboss/JBossLoadTimeWeaver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@
 /**
  * {@link LoadTimeWeaver} implementation for JBoss's instrumentable ClassLoader.
  * Autodetects the specific JBoss version at runtime: currently supports
- * JBoss AS 6 and 7, as well as WildFly 8 (as of Spring 4.0).
+ * JBoss AS 6 and 7, as well as WildFly 8 and 9 (as of Spring 4.2).
  *
  * <p><b>NOTE:</b> On JBoss 6, to avoid the container loading the classes before the
  * application actually starts, one needs to add a <tt>WEB-INF/jboss-scanning.xml</tt>
@@ -62,7 +62,7 @@ public JBossLoadTimeWeaver() {
 	public JBossLoadTimeWeaver(ClassLoader classLoader) {
 		Assert.notNull(classLoader, "ClassLoader must not be null");
 		if (classLoader.getClass().getName().startsWith("org.jboss.modules")) {
-			// JBoss AS 7 or WildFly 8
+			// JBoss AS 7 or WildFly
 			this.adapter = new JBossModulesAdapter(classLoader);
 		}
 		else {

spring-instrument-tomcat/src/main/java/org/springframework/instrument/classloading/tomcat/TomcatInstrumentableClassLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,13 +44,17 @@
  * in the LoadTimeWeaver interface, as expected by ReflectiveLoadTimeWeaver.
  *
  * <p><b>NOTE:</b> Requires Apache Tomcat version 6.0 or higher, as of Spring 4.0.
+ * This class does not work on Tomcat 7.0.63 and higher; please rely on Tomcat's own
+ * {@code InstrumentableClassLoader} facility instead, as autodetected by Spring's
+ * {@link org.springframework.instrument.classloading.tomcat.TomcatLoadTimeWeaver}.
  *
  * @author Costin Leau
  * @author Juergen Hoeller
  * @since 2.0
  * @see #addTransformer
  * @see #getThrowawayClassLoader
  * @see org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver
+ * @see org.springframework.instrument.classloading.tomcat.TomcatLoadTimeWeaver
  */
 public class TomcatInstrumentableClassLoader extends WebappClassLoader {
 

src/asciidoc/core-aop.adoc

@@ -3332,21 +3332,22 @@ environment (summarized in the following table).
 |===
 | Runtime Environment| `LoadTimeWeaver` implementation
 
-| Running in
-  http://www.bea.com/framework.jsp?CNT=index.htm&FP=/content/products/weblogic/server[BEA's
-  Weblogic 10]
+| Running in Oracle's
+  http://www.oracle.com/technetwork/middleware/weblogic/overview/index-085209.html[WebLogic]
 | `WebLogicLoadTimeWeaver`
 
-| Running in http://www-01.ibm.com/software/webservers/appserv/was/[IBM WebSphere
-  Application Server 7]
-| `WebSphereLoadTimeWeaver`
-
-| Running in http://glassfish.dev.java.net/[GlassFish]
+| Running in Oracle's http://glassfish.dev.java.net/[GlassFish]
 | `GlassFishLoadTimeWeaver`
 
-| Running in http://www.jboss.org/jbossas/[JBoss AS]
+| Running in http://tomcat.apache.org/[Apache Tomcat]
+| `TomcatLoadTimeWeaver`
+
+| Running in Red Hat's http://www.jboss.org/jbossas/[JBoss AS] or http://www.wildfly.org/[WildFly]
 | `JBossLoadTimeWeaver`
 
+| Running in IBM's http://www-01.ibm.com/software/webservers/appserv/was/[WebSphere]
+| `WebSphereLoadTimeWeaver`
+
 | JVM started with Spring `InstrumentationSavingAgent` __(java
   -javaagent:path/to/spring-instrument.jar)__
 | `InstrumentationLoadTimeWeaver`
@@ -3443,12 +3444,22 @@ containers.
 
 [[aop-aj-ltw-environment-tomcat]]
 ===== Tomcat
-http://tomcat.apache.org/[Apache Tomcat]'s default class loader does not support class
-transformation which is why Spring provides an enhanced implementation that addresses
-this need. Named `TomcatInstrumentableClassLoader`, the loader works on Tomcat 5.0 and
-above and can be registered individually for __each__ web application as follows:
+Historically, http://tomcat.apache.org/[Apache Tomcat]'s default class loader did not
+support class transformation which is why Spring provides an enhanced implementation
+that addresses this need. Named `TomcatInstrumentableClassLoader`, the loader works on
+Tomcat 6.0 and above.
+
+[TIP]
+====
+Do not define `TomcatInstrumentableClassLoader` anymore as of Tomcat 7.0.44+ / 8.0.
+Instead, let Spring automatically use Tomcat's new native `InstrumentableClassLoader`
+facility through the `TomcatLoadTimeWeaver` strategy, in particular on Tomcat 7.0.63+
+where `TomcatInstrumentableClassLoader` does not work at all anymore.
+====
+
+If you still need to use `TomcatInstrumentableClassLoader`, it can be registered
+individually for __each__ web application as follows:
 
-* Tomcat 6.0.x or higher
 * Copy `org.springframework.instrument.tomcat.jar` into __$CATALINA_HOME__/lib, where
   __$CATALINA_HOME__ represents the root of the Tomcat installation)
 * Instruct Tomcat to use the custom class loader (instead of the default) by editing the