SPR-4493
SPR-6756
This commit is contained in:
Costin Leau
@@ -3504,6 +3504,11 @@ http://www.springframework.org/schema/context
|
|||||||
<entry><para><classname>GlassFishLoadTimeWeaver</classname></para></entry>
|
<entry><para><classname>GlassFishLoadTimeWeaver</classname></para></entry>
|
||||||
</row>
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><para>Running in <ulink url="http://www.jboss.org/jbossas/">JBoss AS</ulink></para></entry>
|
||||||
|
<entry><para><classname>JBossLoadTimeWeaver</classname></para></entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry><para>JVM started with Spring
|
<entry><para>JVM started with Spring
|
||||||
<classname>InstrumentationSavingAgent</classname></para>
|
<classname>InstrumentationSavingAgent</classname></para>
|
||||||
@@ -3514,7 +3519,8 @@ http://www.springframework.org/schema/context
|
|||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry><para>Fallback, expecting the underlying ClassLoader to follow common conventions
|
<entry><para>Fallback, expecting the underlying ClassLoader to follow common conventions
|
||||||
(e.g. applicable to <classname>TomcatInstrumentableClassLoader</classname> and to Resin)</para></entry>
|
(e.g. applicable to <classname>TomcatInstrumentableClassLoader</classname> and
|
||||||
|
<ulink url="http://www.caucho.com/">Resin</ulink>)</para></entry>
|
||||||
<entry><para><classname>ReflectiveLoadTimeWeaver</classname></para></entry>
|
<entry><para><classname>ReflectiveLoadTimeWeaver</classname></para></entry>
|
||||||
</row>
|
</row>
|
||||||
</tbody>
|
</tbody>
|
||||||
@@ -3615,60 +3621,130 @@ http://www.springframework.org/schema/context
|
|||||||
configuration that you will need when using Spring's LTW support in
|
configuration that you will need when using Spring's LTW support in
|
||||||
environments such as application servers and web containers.</para>
|
environments such as application servers and web containers.</para>
|
||||||
|
|
||||||
<section id="aop-aj-ltw-environment-generic">
|
|
||||||
<title>Generic Java applications</title>
|
|
||||||
|
|
||||||
<para>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
|
|
||||||
<literal>-javaagent:path/to/spring-instrument.jar</literal> 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).</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section id="aop-aj-ltw-environment-tomcat">
|
<section id="aop-aj-ltw-environment-tomcat">
|
||||||
<title>Tomcat</title>
|
<title>Tomcat</title>
|
||||||
|
|
||||||
<para>For web applications deployed onto Apache Tomcat 5.0 and above,
|
<para><ulink url="http://tomcat.apache.org/">Apache Tomcat's</ulink> default class loader
|
||||||
Spring provides a <classname>TomcatInstrumentableClassLoader</classname>
|
does not support class transformation which is why Spring provides an enhanced implementation that
|
||||||
to be registered as the web app class loader. The required Tomcat setup
|
addresses this need. Named <classname>TomcatInstrumentableClassLoader</classname>, the loader works
|
||||||
looks as follows, to be included either in Tomcat's central
|
on Tomcat 5.0 and above and can be registered individually for <emphasis>each</emphasis> web application
|
||||||
<literal>server.xml</literal> file or in an application-specific
|
as follows:</para>
|
||||||
<literal>META-INF/context.xml</literal> file within the WAR root.
|
|
||||||
Spring's <literal>org.springframework.instrument.tomcat.jar</literal> needs to be
|
<itemizedlist>
|
||||||
included in Tomcat's common lib directory in order to make this
|
<listitem>
|
||||||
setup work.</para>
|
<para>Tomcat 6.0.x or higher</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
<programlisting language="xml"><Context path="/myWebApp" docBase="/my/webApp/location">
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Copy <literal>org.springframework.instrument.tomcat.jar</literal>
|
||||||
|
into <emphasis>$CATALINA_HOME</emphasis>/lib, where
|
||||||
|
<emphasis>$CATALINA_HOME</emphasis> represents the root of the
|
||||||
|
Tomcat installation)</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Instruct Tomcat to use the custom class loader (instead
|
||||||
|
of the default) by editing the web application context
|
||||||
|
file:</para>
|
||||||
|
|
||||||
|
<programlisting language="xml"><Context path="/myWebApp" docBase="/my/webApp/location">
|
||||||
|
<Loader
|
||||||
|
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/>
|
||||||
|
</Context></programlisting>
|
||||||
|
|
||||||
|
<para>Apache Tomcat 6.0.x (similar to 5.0.x/5.5.x) series
|
||||||
|
supports several context locations: <!--same as before; I can't tell what the different context locations are. It seems like there are only two, not *several*.
|
||||||
|
TR: OK AS IS. See below.-->server configuration file
|
||||||
|
(<emphasis>$CATALINA_HOME/conf/server.xml</emphasis>), the
|
||||||
|
default context configuration
|
||||||
|
(<emphasis>$CATALINA_HOME/conf/context.xml</emphasis>) that
|
||||||
|
affects all deployed web applications and per-web application
|
||||||
|
configurations, <!--change to per-web application? TR: OK.-->deployed
|
||||||
|
on the server side
|
||||||
|
<emphasis>($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml</emphasis>)
|
||||||
|
or inside the web application
|
||||||
|
(<emphasis>your-webapp.war/META-INF/context.xml</emphasis>).
|
||||||
|
For efficiency, inside the web-app configuration style <!--Which one is inside the web-app config style? Reword. TR: REVISED, PLS REVIEW. Same change as for 5.0/5.5-->is
|
||||||
|
recommended because it will impact only applications that use
|
||||||
|
the custom class loader. See the Tomcat 6.0.x <ulink
|
||||||
|
url="http://tomcat.apache.org/tomcat-6.0-doc/config/context.html">documentation</ulink>
|
||||||
|
for more details about available context locations.</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Tomcat 5.0.x/5.5.x</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Copy <literal>org.springframework.instrument.tomcat.jar</literal>
|
||||||
|
into <emphasis>$CATALINA_HOME</emphasis>/server/lib, where
|
||||||
|
<emphasis>$CATALINA_HOME</emphasis> represents the root of the
|
||||||
|
Tomcat installation.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Instruct Tomcat to use the custom class loader instead
|
||||||
|
of the default one by editing the web application context
|
||||||
|
file:</para>
|
||||||
|
|
||||||
|
<programlisting language="xml"><Context path="/myWebApp" docBase="/my/webApp/location">
|
||||||
|
<Loader
|
||||||
|
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/>
|
||||||
|
</Context></programlisting>
|
||||||
|
|
||||||
|
<para>Tomcat 5.0.x and 5.5.x series support several context
|
||||||
|
locations: <!--Revise following sentences so it's clear what the context locations are. As written, it's hard to distinguish how many --><!--locations there are.Seems like only two, not *several*. TR: OK AS IS. There are four locations mentioned.-->server
|
||||||
|
configuration file
|
||||||
|
(<emphasis>$CATALINA_HOME/conf/server.xml</emphasis>), the
|
||||||
|
default context configuration
|
||||||
|
(<emphasis>$CATALINA_HOME/conf/context.xml</emphasis>) that
|
||||||
|
affects all deployed web applications and per-web application
|
||||||
|
configurations, <!--CHanged per-webapp to per-web application. If that's not right, what does it mean?-->deployed
|
||||||
|
on the server side
|
||||||
|
<emphasis>($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml</emphasis>)
|
||||||
|
or inside the web application
|
||||||
|
(<emphasis>your-webapp.war/META-INF/context.xml</emphasis>).
|
||||||
|
For efficiency, inside the web-app configuration style<!--Which of the preceding is *inside the web-app config style*? Two paths contain webapp.
|
||||||
|
TR: REVISED, PLS REVIEW. Chnaged the last one to *inside*--> is recommended
|
||||||
|
recommended because it will impact only applications that use the class loader. See the Tomcat 5.x <ulink
|
||||||
|
url="http://tomcat.apache.org/tomcat-5.5-doc/config/context.html">documentation</ulink>
|
||||||
|
for more details about available context locations.</para>
|
||||||
|
|
||||||
|
<para>Tomcat versions prior to 5.5.20 contained a bug in the
|
||||||
|
XML configuration parsing that prevented usage of the
|
||||||
|
<literal>Loader</literal> tag inside
|
||||||
|
<emphasis>server.xml</emphasis>, regardless of whether a class
|
||||||
|
loader is specified or whether it is the official or a custom
|
||||||
|
one. See Tomcat's bugzilla for <ulink
|
||||||
|
url="http://issues.apache.org/bugzilla/show_bug.cgi?id=39704">more
|
||||||
|
details</ulink>.<!--Will reader know what Tomcat's bugzilla is and where to find it? TR: OK AS IS. They just need to click on the hyerlink.--></para>
|
||||||
|
|
||||||
|
<para>In Tomcat 5.5.20 or later, you should set
|
||||||
|
<emphasis>useSystemClassLoaderAsParent</emphasis> to
|
||||||
|
<literal>false</literal> to fix this problem: <programlisting
|
||||||
|
language="xml"><Context path="/myWebApp" docBase="/my/webApp/location">
|
||||||
<Loader
|
<Loader
|
||||||
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"
|
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"
|
||||||
useSystemClassLoaderAsParent="false"/>
|
useSystemClassLoaderAsParent="false"/>
|
||||||
</Context>
|
</Context></programlisting></para>
|
||||||
</programlisting>
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
<para><emphasis>Note: We generally recommend Tomcat 5.5.20 or above
|
</itemizedlist>
|
||||||
when enabling load-time weaving.</emphasis> Prior versions have known
|
|
||||||
issues with custom <classname>ClassLoader</classname> setup.</para>
|
|
||||||
|
|
||||||
<para>Alternatively, consider the use of the Spring-provided generic
|
<para>Alternatively, consider the use of the Spring-provided generic
|
||||||
VM agent, to be specified in Tomcat's launch script (see above).
|
VM agent, to be specified in Tomcat's launch script (see above).
|
||||||
This will make instrumentation available to all deployed web
|
This will make instrumentation available to all deployed web
|
||||||
applications, no matter which ClassLoader they happen to run on.</para>
|
applications, no matter what ClassLoader they happen to run on.</para>
|
||||||
|
|
||||||
<para>For a more detailed discussion of Tomcat-based weaving setup,
|
|
||||||
check out the <xref linkend="orm-jpa-setup-lcemfb-tomcat"/> 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.</para>
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section id="aop-aj-ltw-environments-weblogic-oc4j-resin-glassfish">
|
<section id="aop-aj-ltw-environments-weblogic-oc4j-resin-glassfish-jboss">
|
||||||
<title>WebLogic, OC4J, Resin, GlassFish</title>
|
<title>WebLogic, OC4J, Resin, GlassFish, JBoss</title>
|
||||||
|
|
||||||
<para>Recent versions of BEA WebLogic (version 10 and above), Oracle
|
<para>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.
|
provide a ClassLoader that is capable of local instrumentation.
|
||||||
Spring's native LTW leverages such ClassLoaders to enable AspectJ weaving.
|
Spring's native LTW leverages such ClassLoaders to enable AspectJ weaving.
|
||||||
You can enable LTW by simply activating <literal>context:load-time-weaver</literal>
|
You can enable LTW by simply activating <literal>context:load-time-weaver</literal>
|
||||||
@@ -3676,10 +3752,34 @@ http://www.springframework.org/schema/context
|
|||||||
need to modify the launch script to add
|
need to modify the launch script to add
|
||||||
<literal>-javaagent:path/to/spring-instrument.jar</literal>.</para>
|
<literal>-javaagent:path/to/spring-instrument.jar</literal>.</para>
|
||||||
|
|
||||||
<para>GlassFish provides an instrumentation-capable ClassLoader as well,
|
<para>Note that GlassFish instrumentation-capable ClassLoader is available only in its EAR environment.
|
||||||
but only in its EAR environment. For GlassFish web applications,
|
For GlassFish web applications, follow the Tomcat setup instructions as outlined above.</para>
|
||||||
follow the Tomcat setup instructions as outlined above.</para>
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
<section id="aop-aj-ltw-environment-generic">
|
||||||
|
<title>Generic Java applications</title>
|
||||||
|
|
||||||
|
<para>When class instrumentation is required in environments that do not support or
|
||||||
|
are not supported by the existing <classname>LoadTimeWeaver</classname>
|
||||||
|
implementations<!--OK? If you mean environments that are not supported by existing impl, revise as shown. If you mean class instrumentation is not supp--><!--orted, say *For environments that require class instrumentation that is not supported...*-->,
|
||||||
|
a JDK agent can be the only solution. For such cases, Spring
|
||||||
|
provides <classname>InstrumentationLoadTimeWeaver</classname>,
|
||||||
|
which requires a Spring-specific (but very general) VM agent,
|
||||||
|
<filename class="libraryfile">org.springframework.instrument-{version}.jar</filename>
|
||||||
|
(previously named <filename class="libraryfile">spring-agent.jar</filename>).</para>
|
||||||
|
|
||||||
|
<para>To use it, you must start the virtual machine with the Spring agent, by
|
||||||
|
supplying the following JVM options:</para>
|
||||||
|
<programlisting>-javaagent:/path/to/org.springframework.instrument-{version}.jar</programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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 <emphasis>entire</emphasis>
|
||||||
|
VM which can prove expensive.</para>
|
||||||
|
<para>For performance reasons, it is recommended to use this configuration only if your target environment
|
||||||
|
(such as <ulink url="http://www.eclipse.org/jetty/">Jetty</ulink>) does not have (or does not support) a dedicated LTW.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
</section>
|
</section>
|
||||||
</section>
|
</section>
|
||||||
|
|||||||
@@ -235,7 +235,7 @@ public class ProductDaoImpl implements ProductDao {
|
|||||||
will then cover the other ORM technologies, showing briefer examples
|
will then cover the other ORM technologies, showing briefer examples
|
||||||
there.</para>
|
there.</para>
|
||||||
|
|
||||||
<para><note>As of Spring 3.0, Spring requires Hibernate 3.2 or later.</note></para>
|
<para><note><para>As of Spring 3.0, Spring requires Hibernate 3.2 or later.</para></note></para>
|
||||||
|
|
||||||
<section id="orm-session-factory-setup">
|
<section id="orm-session-factory-setup">
|
||||||
<title><interfacename>SessionFactory</interfacename> setup in a Spring
|
<title><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
|
applied only <emphasis>per class loader</emphasis> and not per
|
||||||
VM.</para>
|
VM.</para>
|
||||||
|
|
||||||
<para>The following sections will discuss typical JPA weaving setup on
|
<para>Refer to the section <xref linkend="aop-aj-ltw-spring" /> in the AOP chapter for more insight regarding the
|
||||||
Tomcat and with Spring's VM agent. See <xref
|
<interfacename>LoadTimeWeaver</interfacename> implementations and their setup, either generic or customized to
|
||||||
linkend="aop-aj-ltw-spring" /> in the AOP chapter for details on how
|
various platforms (such as Tomcat, WebLogic, OC4J, GlassFish, Resin and JBoss).</para>
|
||||||
to set up general load-time weaving with Tomcat, the VM agent,
|
|
||||||
WebLogic, OC4J, GlassFish, and Resin.</para>
|
|
||||||
|
<para>As described in the aforementioned section, you can configure a context-wide <interfacename>LoadTimeWeaver</interfacename>
|
||||||
|
using the <literal>context:load-time-weaver</literal> configuration element. (This has been available since Spring 2.5.)
|
||||||
|
Such a global weaver is picked up by all JPA <classname>LocalContainerEntityManagerFactoryBeans</classname>
|
||||||
|
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:</para>
|
||||||
|
|
||||||
|
<programlisting language="xml"><context:load-time-weaver/>
|
||||||
|
<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
|
||||||
|
...
|
||||||
|
</bean></programlisting>
|
||||||
|
|
||||||
|
<para> However, if needed, one can manually specify a dedicated weaver through the <literal>loadTimeWeaver</literal> property:</para>
|
||||||
|
|
||||||
<section id="orm-jpa-setup-lcemfb-tomcat">
|
<programlisting language="xml"><bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
|
||||||
<title>Tomcat load-time weaving setup (5.0+)</title>
|
|
||||||
|
|
||||||
<para><ulink url="http://tomcat.apache.org/">Apache Tomcat's</ulink>
|
|
||||||
default class loader does not support class transformation but does
|
|
||||||
allow the use of custom class loaders. Spring offers the
|
|
||||||
<classname>TomcatInstrumentableClassLoader</classname> (in the
|
|
||||||
<literal>org.springframework.instrument.classloading.tomcat</literal>
|
|
||||||
package), which extends the Tomcat class loader
|
|
||||||
(<classname>WebappClassLoader</classname>), and allows JPA
|
|
||||||
<classname>ClassTransformer</classname> instances to enhance all
|
|
||||||
classes loaded by it. In short, JPA transformers are applied only
|
|
||||||
inside a specific web application that uses the
|
|
||||||
<classname>TomcatInstrumentableClassLoader</classname>.</para>
|
|
||||||
|
|
||||||
<para>To use the custom class loader on:</para>
|
|
||||||
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>Tomcat 5.0.x/5.5.x</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<orderedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>Copy <literal>org.springframework.instrument.tomcat.jar</literal>
|
|
||||||
into <emphasis>$CATALINA_HOME</emphasis>/server/lib,where
|
|
||||||
<emphasis>$CATALINA_HOME</emphasis> represents the root of the
|
|
||||||
Tomcat installation.</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>Instruct Tomcat to use the custom class loader instead
|
|
||||||
of the default one by editing the web application context
|
|
||||||
file:</para>
|
|
||||||
|
|
||||||
<programlisting language="xml"><Context path="/myWebApp" docBase="/my/webApp/location">
|
|
||||||
<Loader
|
|
||||||
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/>
|
|
||||||
</Context></programlisting>
|
|
||||||
|
|
||||||
<para>Tomcat 5.0.x and 5.5.x series support several context
|
|
||||||
locations: <!--Revise following sentences so it's clear what the context locations are. As written, it's hard to distinguish how many --><!--locations there are.Seems like only two, not *several*. TR: OK AS IS. There are four locations mentioned.-->server
|
|
||||||
configuration file
|
|
||||||
(<emphasis>$CATALINA_HOME/conf/server.xml</emphasis>), the
|
|
||||||
default context configuration
|
|
||||||
(<emphasis>$CATALINA_HOME/conf/context.xml</emphasis>) that
|
|
||||||
affects all deployed web applications and per-web application
|
|
||||||
configurations, <!--CHanged per-webapp to per-web application. If that's not right, what does it mean?-->deployed
|
|
||||||
on the server
|
|
||||||
<emphasis>($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml</emphasis>)
|
|
||||||
side or inside the web application
|
|
||||||
(<emphasis>your-webapp.war/META-INF/context.xml</emphasis>).
|
|
||||||
For efficiency, inside the web-app configuration style<!--Which of the preceding is *inside the web-app config style*? Two paths contain webapp.
|
|
||||||
TR: REVISED, PLS REVIEW. Chnaged the last one to *inside*--> is recommended
|
|
||||||
because only applications that use JPA will use the custom c
|
|
||||||
lass loader. See the Tomcat 5.x <ulink
|
|
||||||
url="http://tomcat.apache.org/tomcat-5.5-doc/config/context.html">documentation</ulink>
|
|
||||||
for more details about available context locations.</para>
|
|
||||||
|
|
||||||
<para>Tomcat versions prior to 5.5.20 contained a bug in the
|
|
||||||
XML configuration parsing that prevented usage of the
|
|
||||||
<literal>Loader</literal> tag inside
|
|
||||||
<emphasis>server.xml</emphasis>, regardless of whether a class
|
|
||||||
loader is specified or whether it is the official or a custom
|
|
||||||
one. See Tomcat's bugzilla for <ulink
|
|
||||||
url="http://issues.apache.org/bugzilla/show_bug.cgi?id=39704">more
|
|
||||||
details</ulink>.<!--Will reader know what Tomcat's bugzilla is and where to find it? TR: OK AS IS. They just need to click on the hyerlink.--></para>
|
|
||||||
|
|
||||||
<para>In Tomcat 5.5.20 or later, you can set
|
|
||||||
<emphasis>useSystemClassLoaderAsParent</emphasis> to
|
|
||||||
<literal>false</literal> to fix the problem: <programlisting
|
|
||||||
language="xml"><Context path="/myWebApp" docBase="/my/webApp/location">
|
|
||||||
<Loader
|
|
||||||
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"
|
|
||||||
useSystemClassLoaderAsParent="false"/>
|
|
||||||
</Context></programlisting></para>
|
|
||||||
</listitem>
|
|
||||||
</orderedlist>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>Tomcat 6.0.x</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<orderedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>Copy <literal>org.springframework.instrument.tomcat.jar</literal>
|
|
||||||
into <emphasis>$CATALINA_HOME</emphasis>/lib, where
|
|
||||||
<emphasis>$CATALINA_HOME</emphasis> represents the root of the
|
|
||||||
Tomcat installation)</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>Instruct Tomcat to use the custom class loader (instead
|
|
||||||
of the default) by editing the web application context
|
|
||||||
file:</para>
|
|
||||||
|
|
||||||
<programlisting language="xml"><Context path="/myWebApp" docBase="/my/webApp/location">
|
|
||||||
<Loader
|
|
||||||
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/>
|
|
||||||
</Context></programlisting>
|
|
||||||
|
|
||||||
<para>The Tomcat 6.0.x (similar to 5.0.x/5.5.x) series
|
|
||||||
supports several context locations: <!--same as before; I can't tell what the different context locations are. It seems like there are only two, not *several*.
|
|
||||||
TR: OK AS IS. See above.-->server configuration file
|
|
||||||
(<emphasis>$CATALINA_HOME/conf/server.xml</emphasis>), the
|
|
||||||
default context configuration
|
|
||||||
(<emphasis>$CATALINA_HOME/conf/context.xml</emphasis>) that
|
|
||||||
affects all deployed web applications and per-web application
|
|
||||||
configurations, <!--change to per-web application? TR: OK.-->deployed
|
|
||||||
on the server
|
|
||||||
<emphasis>($CATALINA_HOME/conf/[enginename]/[hostname]/my-webapp-context.xml</emphasis>)
|
|
||||||
side or inside the web application
|
|
||||||
(<emphasis>your-webapp.war/META-INF/context.xml</emphasis>).
|
|
||||||
For efficiency, inside the web-app configuration style <!--Which one is inside the web-app config style? Reword. TR: REVISED, PLS REVIEW. Same change as for 5.0/5.5-->is
|
|
||||||
recommended because only applications that use JPA will use
|
|
||||||
the custom class loader. See the Tomcat 6.0.x <ulink
|
|
||||||
url="http://tomcat.apache.org/tomcat-6.0-doc/config/context.html">documentation</ulink>
|
|
||||||
for more details about available context locations.</para>
|
|
||||||
</listitem>
|
|
||||||
</orderedlist>
|
|
||||||
</itemizedlist>
|
|
||||||
|
|
||||||
<para>The last step required on all Tomcat versions is to use the
|
|
||||||
appropriate <interfacename>LoadTimeWeaver</interfacename> when you
|
|
||||||
configure
|
|
||||||
<classname>LocalContainerEntityManagerFactoryBean</classname>:</para>
|
|
||||||
|
|
||||||
<programlisting language="xml"><bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
|
|
||||||
<property name="loadTimeWeaver">
|
<property name="loadTimeWeaver">
|
||||||
<bean class="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/>
|
<bean class="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/>
|
||||||
</property>
|
</property>
|
||||||
</bean></programlisting>
|
</bean></programlisting>
|
||||||
|
|
||||||
<para>Using this technique, JPA applications relying on
|
<para>No matter how the LTW is configured, using this technique, JPA applications relying on
|
||||||
instrumentation, and can run in Tomcat without needing an agent.
|
instrumentation can run in the target platform (ex: Tomcat) without needing an agent.
|
||||||
This is important especially when Tomcat is hosting applications
|
This is important especially when the hosting applications rely on different JPA implementations
|
||||||
that rely on different JPA implementations because the JPA
|
because the JPA transformers are applied only at class loader level and thus are
|
||||||
transformers are applied only at class loader level and thus are
|
|
||||||
isolated from each other.</para>
|
isolated from each other.</para>
|
||||||
|
|
||||||
<note>
|
<!--
|
||||||
|
<note>
|
||||||
<para>If you use TopLink Essentials as a JPA provider under
|
<para>If you use TopLink Essentials as a JPA provider under
|
||||||
Tomcat, place the toplink-essentials JAR under
|
Tomcat, place the toplink-essentials JAR under
|
||||||
<emphasis>$CATALINA_HOME</emphasis>/shared/lib folder instead of
|
<emphasis>$CATALINA_HOME</emphasis>/shared/lib folder instead of
|
||||||
inside your war.<!--Revise: *instead of placing the JAR under your WAR*, OR *instead of placing WAR under $CATALINA_HOME/etc*?
|
inside your war.--><!--Revise: *instead of placing the JAR under your WAR*, OR *instead of placing WAR under $CATALINA_HOME/etc*?
|
||||||
TR: REVISED, PLS REVIEW. Should be *inside your war*.--></para>
|
TR: REVISED, PLS REVIEW. Should be *inside your war*. --><!-- </para>
|
||||||
</note>
|
</note>
|
||||||
</section>
|
-->
|
||||||
|
|
||||||
<section id="orm-jpa-setup-lcemfb-agent">
|
|
||||||
<title>General load-time weaving with the VM agent</title>
|
|
||||||
|
|
||||||
<para>For environments that require class instrumentation but are
|
|
||||||
not supported by the existing <classname>LoadTimeWeaver</classname>
|
|
||||||
implementations<!--OK? If you mean environments that are not supported by existing impl, revise as shown. If you mean class instrumentation is not supp--><!--orted, say *For environments that require class instrumentation that is not supported...*-->,
|
|
||||||
a JDK agent can be the only solution. For such cases, Spring
|
|
||||||
provides <classname>InstrumentationLoadTimeWeaver</classname>,
|
|
||||||
which requires a Spring-specific (but very general) VM agent,
|
|
||||||
<filename class="libraryfile">org.springframework.instrument-{version}.jar</filename>
|
|
||||||
(previously named <filename class="libraryfile">spring-agent.jar</filename>):</para>
|
|
||||||
|
|
||||||
<programlisting language="xml"><bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
|
|
||||||
<property name="loadTimeWeaver">
|
|
||||||
<bean class="org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver"/>
|
|
||||||
</property>
|
|
||||||
</bean></programlisting>
|
|
||||||
|
|
||||||
<para>You must start the virtual machine with the Spring agent, by
|
|
||||||
supplying the following JVM options:</para>
|
|
||||||
|
|
||||||
<programlisting>-javaagent:/path/to/org.springframework.instrument-{version}.jar</programlisting>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section id="orm-jpa-setup-lcemfb-weaver">
|
|
||||||
<title>Context-wide load-time weaver setup</title>
|
|
||||||
|
|
||||||
<para>You can configure a context-wide
|
|
||||||
<interfacename>LoadTimeWeaver</interfacename> using the
|
|
||||||
<literal>context:load-time-weaver</literal> configuration element. (This
|
|
||||||
has been available since Spring 2.5.)
|
|
||||||
Such a global weaver is picked up by all JPA
|
|
||||||
<classname>LocalContainerEntityManagerFactoryBeans</classname>
|
|
||||||
automatically.</para>
|
|
||||||
|
|
||||||
<para>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.</para>
|
|
||||||
|
|
||||||
<programlisting language="xml"><context:load-time-weaver/>
|
|
||||||
|
|
||||||
<bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
|
|
||||||
...
|
|
||||||
</bean></programlisting>
|
|
||||||
|
|
||||||
<para>See <xref linkend="aop-aj-ltw-spring" /> 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.</para>
|
|
||||||
</section>
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section id="orm-jpa-multiple-pu">
|
<section id="orm-jpa-multiple-pu">
|
||||||
|
|||||||
Reference in New Issue
Block a user