Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SPR-4493

Browse Source 
SPR-6756
This commit is contained in:
Costin Leau
2010-01-25 17:03:05 +00:00
parent 0c2a710787
commit bc37c50972
2 changed files with 171 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
spring-framework-reference/src/orm.xml
View File

@@ -235,7 +235,7 @@ public class ProductDaoImpl implements ProductDao {
will then cover the other ORM technologies, showing briefer examples
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">
<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
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>
<para>Refer to the section <xref linkend="aop-aj-ltw-spring" /> in the AOP chapter for more insight regarding the
<interfacename>LoadTimeWeaver</interfacename> implementations and their setup, either generic or customized to
various platforms (such as Tomcat, WebLogic, OC4J, GlassFish, Resin and JBoss).</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">&lt;context:load-time-weaver/&gt;
&lt;bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
...
&lt;/bean&gt;</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">
<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">&lt;Context path="/myWebApp" docBase="/my/webApp/location"&gt;
&lt;Loader
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/&gt;
&lt;/Context&gt;</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">&lt;Context path="/myWebApp" docBase="/my/webApp/location"&gt;
&lt;Loader
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"
useSystemClassLoaderAsParent="false"/&gt;
&lt;/Context&gt;</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">&lt;Context path="/myWebApp" docBase="/my/webApp/location"&gt;
&lt;Loader
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/&gt;
&lt;/Context&gt;</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">&lt;bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
<programlisting language="xml">&lt;bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
&lt;property name="loadTimeWeaver"&gt;
&lt;bean class="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/&gt;
&lt;/property&gt;
&lt;/bean&gt;</programlisting>
<para>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
<para>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.</para>
<note>
<!--
<note>
<para>If you use TopLink Essentials as a JPA provider under
Tomcat, place the toplink-essentials JAR under
<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*?
TR: REVISED, PLS REVIEW. Should be *inside your war*.--></para>
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>
</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">&lt;bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
&lt;property name="loadTimeWeaver"&gt;
&lt;bean class="org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver"/&gt;
&lt;/property&gt;
&lt;/bean&gt;</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">&lt;context:load-time-weaver/&gt;
&lt;bean id="emf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
...
&lt;/bean&gt;</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 id="orm-jpa-multiple-pu">