diff --git a/spring-framework-reference/src/aop.xml b/spring-framework-reference/src/aop.xml index 259477ea7a7..77ed9edec7d 100644 --- a/spring-framework-reference/src/aop.xml +++ b/spring-framework-reference/src/aop.xml @@ -3504,6 +3504,11 @@ http://www.springframework.org/schema/context GlassFishLoadTimeWeaver + + Running in JBoss AS + JBossLoadTimeWeaver + + JVM started with Spring InstrumentationSavingAgent @@ -3514,7 +3519,8 @@ http://www.springframework.org/schema/context Fallback, expecting the underlying ClassLoader to follow common conventions - (e.g. applicable to TomcatInstrumentableClassLoader and to Resin) + (e.g. applicable to TomcatInstrumentableClassLoader and + Resin) ReflectiveLoadTimeWeaver @@ -3615,60 +3621,130 @@ http://www.springframework.org/schema/context configuration that you will need when using Spring's LTW support in environments such as application servers and web containers. -
- Generic Java applications - - You may enable Spring's support for LTW in any Java application - (standalone as well as application server based) through the use of - the Spring-provided instrumentation agent. To do so, start - the VM by by specifying the - -javaagent:path/to/spring-instrument.jar option. - Note that this requires modification of the VM launch script - which may prevent you from using this in application server - environments (depending on your operation policies). -
-
Tomcat - For web applications deployed onto Apache Tomcat 5.0 and above, - Spring provides a TomcatInstrumentableClassLoader - to be registered as the web app class loader. The required Tomcat setup - looks as follows, to be included either in Tomcat's central - server.xml file or in an application-specific - META-INF/context.xml file within the WAR root. - Spring's org.springframework.instrument.tomcat.jar needs to be - included in Tomcat's common lib directory in order to make this - setup work. - - <Context path="/myWebApp" docBase="/my/webApp/location"> + 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: + + + + 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 web application context + file: + + <Context path="/myWebApp" docBase="/my/webApp/location"> + <Loader + loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/> +</Context> + + Apache Tomcat 6.0.x (similar to 5.0.x/5.5.x) series + supports several context locations: server configuration file + ($CATALINA_HOME/conf/server.xml), the + default context configuration + ($CATALINA_HOME/conf/context.xml) that + affects all deployed web applications and per-web application + configurations, deployed + on the server side + ($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml) + or inside the web application + (your-webapp.war/META-INF/context.xml). + For efficiency, inside the web-app configuration style is + recommended because it will impact only applications that use + the custom class loader. See the Tomcat 6.0.x documentation + for more details about available context locations. + + + + + Tomcat 5.0.x/5.5.x + + + + + Copy org.springframework.instrument.tomcat.jar + into $CATALINA_HOME/server/lib, where + $CATALINA_HOME represents the root of the + Tomcat installation. + + + + Instruct Tomcat to use the custom class loader instead + of the default one by editing the web application context + file: + + <Context path="/myWebApp" docBase="/my/webApp/location"> + <Loader + loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/> +</Context> + + Tomcat 5.0.x and 5.5.x series support several context + locations: server + configuration file + ($CATALINA_HOME/conf/server.xml), the + default context configuration + ($CATALINA_HOME/conf/context.xml) that + affects all deployed web applications and per-web application + configurations, deployed + on the server side + ($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml) + or inside the web application + (your-webapp.war/META-INF/context.xml). + For efficiency, inside the web-app configuration style is recommended + recommended because it will impact only applications that use the class loader. See the Tomcat 5.x documentation + for more details about available context locations. + + Tomcat versions prior to 5.5.20 contained a bug in the + XML configuration parsing that prevented usage of the + Loader tag inside + server.xml, regardless of whether a class + loader is specified or whether it is the official or a custom + one. See Tomcat's bugzilla for more + details. + + In Tomcat 5.5.20 or later, you should set + useSystemClassLoaderAsParent to + false to fix this problem: <Context path="/myWebApp" docBase="/my/webApp/location"> <Loader loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader" useSystemClassLoaderAsParent="false"/> -</Context> - - - Note: We generally recommend Tomcat 5.5.20 or above - when enabling load-time weaving. Prior versions have known - issues with custom ClassLoader setup. +</Context> + + + Alternatively, consider the use of the Spring-provided generic VM agent, to be specified in Tomcat's launch script (see above). This will make instrumentation available to all deployed web - applications, no matter which ClassLoader they happen to run on. - - For a more detailed discussion of Tomcat-based weaving setup, - check out the section - which discusses specifics of various Tomcat versions. While the primary - focus of that section is on JPA persistence provider setup, the Tomcat - setup characteristics apply to general load-time weaving as well. + applications, no matter what ClassLoader they happen to run on.
-
- WebLogic, OC4J, Resin, GlassFish +
+ WebLogic, OC4J, Resin, GlassFish, JBoss Recent versions of BEA WebLogic (version 10 and above), Oracle - Containers for Java EE (OC4J 10.1.3.1 and above) and Resin (3.1 and above) + Containers for Java EE (OC4J 10.1.3.1 and above), Resin (3.1 and above) and JBoss (5.x or above) provide a ClassLoader that is capable of local instrumentation. Spring's native LTW leverages such ClassLoaders to enable AspectJ weaving. You can enable LTW by simply activating context:load-time-weaver @@ -3676,10 +3752,34 @@ http://www.springframework.org/schema/context need to modify the launch script to add -javaagent:path/to/spring-instrument.jar. - GlassFish provides an instrumentation-capable ClassLoader as well, - but only in its EAR environment. For GlassFish web applications, - follow the Tomcat setup instructions as outlined above. + Note that GlassFish instrumentation-capable ClassLoader is available only in its EAR environment. + For GlassFish web applications, follow the Tomcat setup instructions as outlined above.
+ +
+ Generic Java applications + + When class instrumentation is required in environments that do not support or + are not supported by the existing LoadTimeWeaver + implementations, + a JDK agent can be the only solution. For such cases, Spring + provides InstrumentationLoadTimeWeaver, + which requires a Spring-specific (but very general) VM agent, + org.springframework.instrument-{version}.jar + (previously named spring-agent.jar). + + To use it, you must start the virtual machine with the Spring agent, by + supplying the following JVM options: + -javaagent:/path/to/org.springframework.instrument-{version}.jar + + + Note that this requires modification of the VM launch script which may prevent you from using this in application server + environments (depending on your operation policies). Additionally, the JDK agent will instrument the entire + VM which can prove expensive. + For performance reasons, it is recommended to use this configuration only if your target environment + (such as Jetty) does not have (or does not support) a dedicated LTW. +
+
diff --git a/spring-framework-reference/src/orm.xml b/spring-framework-reference/src/orm.xml index c4bc4b7f745..ca94de03902 100644 --- a/spring-framework-reference/src/orm.xml +++ b/spring-framework-reference/src/orm.xml @@ -235,7 +235,7 @@ public class ProductDaoImpl implements ProductDao { will then cover the other ORM technologies, showing briefer examples there. - As of Spring 3.0, Spring requires Hibernate 3.2 or later. + As of Spring 3.0, Spring requires Hibernate 3.2 or later.
<interfacename>SessionFactory</interfacename> setup in a Spring @@ -1467,211 +1467,45 @@ TR: OK AS IS. The requirement is to provide the classloader for the runtime envi applied only <emphasis>per class loader</emphasis> and not per VM.</para> - <para>The following sections will discuss typical JPA weaving setup on - Tomcat and with Spring's VM agent. See <xref - linkend="aop-aj-ltw-spring" /> in the AOP chapter for details on how - to set up general load-time weaving with Tomcat, the VM agent, - WebLogic, OC4J, GlassFish, and Resin.</para> - - <section id="orm-jpa-setup-lcemfb-tomcat"> - <title>Tomcat load-time weaving setup (5.0+) - - Apache Tomcat's - default class loader does not support class transformation but does - allow the use of custom class loaders. Spring offers the - TomcatInstrumentableClassLoader (in the - org.springframework.instrument.classloading.tomcat - package), which extends the Tomcat class loader - (WebappClassLoader), and allows JPA - ClassTransformer instances to enhance all - classes loaded by it. In short, JPA transformers are applied only - inside a specific web application that uses the - TomcatInstrumentableClassLoader. - - To use the custom class loader on: - - - - Tomcat 5.0.x/5.5.x - - - - - Copy org.springframework.instrument.tomcat.jar - into $CATALINA_HOME/server/lib,where - $CATALINA_HOME represents the root of the - Tomcat installation. - - - - Instruct Tomcat to use the custom class loader instead - of the default one by editing the web application context - file: - - <Context path="/myWebApp" docBase="/my/webApp/location"> - <Loader - loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/> -</Context> - - Tomcat 5.0.x and 5.5.x series support several context - locations: server - configuration file - ($CATALINA_HOME/conf/server.xml), the - default context configuration - ($CATALINA_HOME/conf/context.xml) that - affects all deployed web applications and per-web application - configurations, deployed - on the server - ($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml) - side or inside the web application - (your-webapp.war/META-INF/context.xml). - For efficiency, inside the web-app configuration style is recommended - because only applications that use JPA will use the custom c - lass loader. See the Tomcat 5.x documentation - for more details about available context locations. - - Tomcat versions prior to 5.5.20 contained a bug in the - XML configuration parsing that prevented usage of the - Loader tag inside - server.xml, regardless of whether a class - loader is specified or whether it is the official or a custom - one. See Tomcat's bugzilla for more - details. - - In Tomcat 5.5.20 or later, you can set - useSystemClassLoaderAsParent to - false to fix the problem: <Context path="/myWebApp" docBase="/my/webApp/location"> - <Loader - loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader" - useSystemClassLoaderAsParent="false"/> -</Context> - - - - - Tomcat 6.0.x - - - - - 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 web application context - file: - - <Context path="/myWebApp" docBase="/my/webApp/location"> - <Loader - loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/> -</Context> - - The Tomcat 6.0.x (similar to 5.0.x/5.5.x) series - supports several context locations: server configuration file - ($CATALINA_HOME/conf/server.xml), the - default context configuration - ($CATALINA_HOME/conf/context.xml) that - affects all deployed web applications and per-web application - configurations, deployed - on the server - ($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml) - side or inside the web application - (your-webapp.war/META-INF/context.xml). - For efficiency, inside the web-app configuration style is - recommended because only applications that use JPA will use - the custom class loader. See the Tomcat 6.0.x documentation - for more details about available context locations. - - - - - The last step required on all Tomcat versions is to use the - appropriate LoadTimeWeaver when you - configure - LocalContainerEntityManagerFactoryBean: - - <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> + Refer to the section in the AOP chapter for more insight regarding the + LoadTimeWeaver implementations and their setup, either generic or customized to + various platforms (such as Tomcat, WebLogic, OC4J, GlassFish, Resin and JBoss). + + + As described in the aforementioned section, you can configure a context-wide LoadTimeWeaver + using the context:load-time-weaver configuration element. (This has been available since Spring 2.5.) + Such a global weaver is picked up by all JPA LocalContainerEntityManagerFactoryBeans + automatically. This is the preferred way of setting up a load-time weaver, delivering autodetection of the platform + (WebLogic, OC4J, GlassFish, Tomcat, Resin, JBoss or VM agent) and automatic propagation of the weaver to all weaver-aware beans: + + <context:load-time-weaver/> +<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> + ... +</bean> + + However, if needed, one can manually specify a dedicated weaver through the loadTimeWeaver property: + + <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> <property name="loadTimeWeaver"> <bean class="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/> </property> </bean> - Using this technique, JPA applications relying on - instrumentation, and can run in Tomcat without needing an agent. - This is important especially when Tomcat is hosting applications - that rely on different JPA implementations because the JPA - transformers are applied only at class loader level and thus are + No matter how the LTW is configured, using this technique, JPA applications relying on + instrumentation can run in the target platform (ex: Tomcat) without needing an agent. + This is important especially when the hosting applications rely on different JPA implementations + because the JPA transformers are applied only at class loader level and thus are isolated from each other. - + + inside your war.-->, - a JDK agent can be the only solution. For such cases, Spring - provides InstrumentationLoadTimeWeaver, - which requires a Spring-specific (but very general) VM agent, - org.springframework.instrument-{version}.jar - (previously named spring-agent.jar): - - <bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> - <property name="loadTimeWeaver"> - <bean class="org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver"/> - </property> -</bean> - - You must start the virtual machine with the Spring agent, by - supplying the following JVM options: - - -javaagent:/path/to/org.springframework.instrument-{version}.jar -
- -
- Context-wide load-time weaver setup - - You can configure a context-wide - LoadTimeWeaver using the - context:load-time-weaver configuration element. (This - has been available since Spring 2.5.) - Such a global weaver is picked up by all JPA - LocalContainerEntityManagerFactoryBeans - automatically. - - This is the preferred way of setting up a load-time weaver, - delivering autodetection of the platform (WebLogic, OC4J, GlassFish, - Tomcat, Resin, or VM agent) and automatic propagation of the weaver - to all weaver-aware beans. - - <context:load-time-weaver/> - -<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> - ... -</bean> - - See for details on how to - set up general load-time weaving, covering Tomcat and the VM agent - as well as WebLogic, OC4J, GlassFish and Resin. -
+ -->