openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] OpenJPA > Entity Enhancement
Date Thu, 08 Nov 2012 17:22:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/5/_/styles/combined.css?spaceKey=openjpa&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/openjpa/Entity+Enhancement">Entity
Enhancement</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~kwsutter@gmail.com">Kevin
Sutter</a>
    </h4>
        <br/>
                         <h4>Changes (23)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. What is Enhancement Anyway? <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >The JPA spec requires some type
of monitoring of Entity objects, but the spec does not define how to implement this monitoring.
Some JPA providers auto-generate new subclasses or proxy objects that front the user&#39;s
Entity objects at runtime, while others use byte-code weaving technologies to enhance the
actual Entity class <span class="diff-changed-words">objects<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">
at build time</span>.</span>  OpenJPA supports both <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">methods,</span>
<span class="diff-added-words"style="background-color: #dfd;">mechanisms,</span>
but strongly suggests only using the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">*build
time*</span> <span class="diff-added-words"style="background-color: #dfd;">[*byte-code
weaving*|#byte-code]</span> enhancement. <span class="diff-added-words"style="background-color:
#dfd;"> The [subclassing|#subclassing] support (as provided by OpenJPA) is not recommended
(and is disabled by default in OpenJPA 2.0 and beyond).</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br>For complete details on
entity enhancement, please checkout the section in the latest [User&#39;s Guide on Enhancement|http://openjpa.apache.org/builds/latest/docs/manual/manual.html#ref_guide_pc_enhance].
 The following sections will only cover the high-level concepts and the ways to use the enhancer
in different build and runtime setups. <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:byte-code}
<br>h2. Byte-code Weaving Enhancement <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2.
Build Time Enhancement <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Byte-code
weaving is the preferred and recommended method of enhancement to use with OpenJPA.  This
byte-code enhancement can be performed at [´╗┐build-time|#build-time] or dynamically at [run-time|#dynamic].
 Whichever approach is selected, the same enhancement processing is performed with the same
level of functionality weaved into each Entity class. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Build
time enhancement is the recommended method to use with OpenJPA, as it it the fastest and most
reliable method.  Please follow the links below based on your development environment: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:build-time}
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Build Time Enhancement <br> <br>Build time enhancement is probably the most common
enhancement method to use with OpenJPA, especially in an automated JUnit test environment.
 The whole OpenJPA JUnit test bucket relies on build-time enhancement.  Please follow the
links below based on your development environment: <br> <br></td></tr>
            <tr><td class="diff-unchanged" >* [Enhancement with ANT] <br>*
[Enhancement with Maven] <br>* [Enhancement with Eclipse] <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:dynamic}
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2.
Runtime Enhancement <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Dynamic Enhancement <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">When
running in a Java SE environment or in a non-Java EE 5 compliant container, OpenJPA defaults
to using runtime subclassing enhancement. The subclassing enhancement support was added originally
as a convenience to new developers to reduce the amount of work to get a &#39;HelloWorld-ish&#39;
OpenJPA application working out of the box. It was never meant to run in production. So you&#39;re
probably thinking that this sounds great! OpenJPA handles enhancement automatically for me
and I can stop reading this post. Wrong! Subclassing has two major drawbacks. First off, it
isn&#39;t nearly as fast as byte-code enhancement and the second drawback is that there
are some documented functional problems when using the subclassing support. The moral of the
story is, don&#39;t use this method of enhancement. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Dynamic
run-time enhancement with OpenJPA comes in several different flavors, depending on your environment.
 The preferred and most reliable method of dynamic enhancement is via the defined container
hook in a [Java EE and OSGi environments|#javaee].  In a [JSE environment|#jse], there are
a couple of choices for configuring or using dynamic enhancement.  The choice will depend
on your usage patterns. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">If
you really want to use runtime enhancement, the following [Runtime Enhancement] page describes
how to use the _-javaagent_ setting in ANT and Eclipse projects. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:javaee}
<br>h4. Java EE and OSGi environments <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Additional
information regarding the subclassing enhancement can be found in the [OpenJPA docs|http://openjpa.apache.org/builds/latest/docs/manual/manual.html#ref_guide_pc_enhance].
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
Java EE specifications outline a mechanism for plugging in a JPA transformer (byte code enhancer)
into the container&#39;s classloading processing.  Most Java EE application servers (for
example, IBM&#39;s WebSphere Application Server) support this mechanism.  In addition,
several of the OSGi container providers (for example, WebSphere&#39;s OSGi container)
have followed a similar path and provide this classloading hook for dynamic enhancement. 
If your container environment supports this mechanism with OpenJPA, this would be the preferred
and easiest method of performing the byte-code enhancement. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2.
Dynamic Enhancement <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:jse}
<br>h4. JSE Environment <br>h5. Explicit javaagent support <br>The recommended
way get runtime enhancement for the JSE environment is to provide a javaagent when launching
the JVM that OpenJPA is running in. This is a common method to use when executing individual
JUnits in a development environment because it is very painless and easy. All that is required
to get runtime enhancement is to specify the -javaagent:openjpa-all-2.2.0-SNAPSHOT.jar (as
an example) on the JVM configuration. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">More
information can be found on the [Runtime Enhancement] page. <br> <br>h5. Implicit
javaagent support <br></td></tr>
            <tr><td class="diff-unchanged" >[OPENJPA-952|https://issues.apache.org/jira/browse/OPENJPA-952]
added the capability to have OpenJPA attempt to dynamically load the javaagent enhancer. If
you see the following message, OpenJPA loaded the enhancer dynamically. <br>bq. \[java\]
1453  jpa_app  INFO   \[main\] openjpa.Runtime - OpenJPA dynamically loaded the class enhancer.
Any classes that were not enhanced at build time will be enhanced when the are loaded by the
JVM. <br></td></tr>
            <tr><td class="diff-unchanged" >This method of enhancement is intended
for first time users or developers as it has a number of caveats. <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">*
It only works on Sun 1.6SDK, not the JRE and IBM JDK (SR8+). <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">*
It works with both the Sun/Oracle 1.6SDK and IBM 1.6JDK.  The JRE is not sufficient. <br></td></tr>
            <tr><td class="diff-unchanged" >* If any unenhanced Entities are loaded
by the JVM before an EntityManagerFactory is created, this method of enhancement will not
work. If this condition is encountered, you will see the following warning: <br>bq.
\[java\] 1047  jpa_app  WARN   \[main\] openjpa.Enhance - Unenhanced classes were detected
even though the enhancer has ran. Ensure that the EntityManagerFactory is created prior to
creating any Entities. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >If your application uses some
other method of enhancement, this support can be <span class="diff-added-words"style="background-color:
#dfd;">explicitly</span> disabled by setting the following property in your persistence.xml.
<br></td></tr>
            <tr><td class="diff-unchanged" >bq. &lt;property name=&quot;openjpa.DynamicEnhancementAgent&quot;
value=&quot;false&quot;/&gt; <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:subclassing}
<br>h2. Subclassing Enhancement <br> <br>{note:title=Not Recommended} <br>The
use of OpenJPA&#39;s subclassing support is not recommended, and is disabled by default
in OpenJPA 2.0 and beyond. <br>{note} <br>When running in a Java SE environment
or in a non-Java EE 5 compliant container, OpenJPA can utilize runtime subclassing enhancement.
The subclassing enhancement support was added originally as a convenience to new developers
to reduce the amount of work to get a &#39;HelloWorld-ish&#39; OpenJPA application
working out of the box. It was never meant to run in production. So you&#39;re probably
thinking that this sounds great\! OpenJPA handles enhancement automatically for me and I can
stop reading this post. Wrong\! Subclassing has two major drawbacks. First off, it isn&#39;t
nearly as fast as byte-code enhancement and the second drawback is that there are some documented
functional problems when using the subclassing support. The moral of the story is, don&#39;t
use this method of enhancement. <br> <br>For reference, the property that enables/disables
the subclassing support is openjpa.RuntimeUnenhancedClasses.  The value &quot;unsupported&quot;
is the recommended and default setting for this property. <br> <br>Additional
information regarding the subclassing enhancement can be found in the [OpenJPA docs|http://openjpa.apache.org/builds/latest/docs/manual/manual.html#ref_guide_pc_enhance].
<br> <br></td></tr>
            <tr><td class="diff-unchanged" >h2. Author Attribution <br>
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        

<h1><a name="EntityEnhancement-WhatisEnhancementAnyway%3F"></a>What is Enhancement
Anyway?</h1>

<p>The JPA spec requires some type of monitoring of Entity objects, but the spec does
not define how to implement this monitoring. Some JPA providers auto-generate new subclasses
or proxy objects that front the user's Entity objects at runtime, while others use byte-code
weaving technologies to enhance the actual Entity class objects.  OpenJPA supports both mechanisms,
but strongly suggests only using the <a href="#EntityEnhancement-bytecode"><b>byte-code
weaving</b></a> enhancement.  The <a href="#EntityEnhancement-subclassing">subclassing</a>
support (as provided by OpenJPA) is not recommended (and is disabled by default in OpenJPA
2.0 and beyond).</p>

<p>For complete details on entity enhancement, please checkout the section in the latest
<a href="http://openjpa.apache.org/builds/latest/docs/manual/manual.html#ref_guide_pc_enhance"
class="external-link" rel="nofollow">User's Guide on Enhancement</a>.  The following
sections will only cover the high-level concepts and the ways to use the enhancer in different
build and runtime setups.</p>

<p><a name="EntityEnhancement-bytecode"></a></p>
<h2><a name="EntityEnhancement-BytecodeWeavingEnhancement"></a>Byte-code
Weaving Enhancement</h2>

<p>Byte-code weaving is the preferred and recommended method of enhancement to use with
OpenJPA.  This byte-code enhancement can be performed at <a href="#EntityEnhancement-buildtime">´╗┐build-time</a>
or dynamically at <a href="#EntityEnhancement-dynamic">run-time</a>.  Whichever
approach is selected, the same enhancement processing is performed with the same level of
functionality weaved into each Entity class.</p>

<p><a name="EntityEnhancement-buildtime"></a></p>

<h3><a name="EntityEnhancement-BuildTimeEnhancement"></a>Build Time Enhancement</h3>

<p>Build time enhancement is probably the most common enhancement method to use with
OpenJPA, especially in an automated JUnit test environment.  The whole OpenJPA JUnit test
bucket relies on build-time enhancement.  Please follow the links below based on your development
environment:</p>

<ul>
	<li><a href="/confluence/display/openjpa/Enhancement+with+ANT" title="Enhancement
with ANT">Enhancement with ANT</a></li>
	<li><a href="/confluence/display/openjpa/Enhancement+with+Maven" title="Enhancement
with Maven">Enhancement with Maven</a></li>
	<li><a href="/confluence/display/openjpa/Enhancement+with+Eclipse" title="Enhancement
with Eclipse">Enhancement with Eclipse</a></li>
</ul>


<p><a name="EntityEnhancement-dynamic"></a></p>

<h3><a name="EntityEnhancement-DynamicEnhancement"></a>Dynamic Enhancement</h3>

<p>Dynamic run-time enhancement with OpenJPA comes in several different flavors, depending
on your environment.  The preferred and most reliable method of dynamic enhancement is via
the defined container hook in a <a href="#EntityEnhancement-javaee">Java EE and OSGi
environments</a>.  In a <a href="#EntityEnhancement-jse">JSE environment</a>,
there are a couple of choices for configuring or using dynamic enhancement.  The choice will
depend on your usage patterns.</p>

<p><a name="EntityEnhancement-javaee"></a></p>
<h4><a name="EntityEnhancement-JavaEEandOSGienvironments"></a>Java EE and
OSGi environments</h4>

<p>The Java EE specifications outline a mechanism for plugging in a JPA transformer
(byte code enhancer) into the container's classloading processing.  Most Java EE application
servers (for example, IBM's WebSphere Application Server) support this mechanism.  In addition,
several of the OSGi container providers (for example, WebSphere's OSGi container) have followed
a similar path and provide this classloading hook for dynamic enhancement.  If your container
environment supports this mechanism with OpenJPA, this would be the preferred and easiest
method of performing the byte-code enhancement.</p>

<p><a name="EntityEnhancement-jse"></a></p>
<h4><a name="EntityEnhancement-JSEEnvironment"></a>JSE Environment</h4>
<h5><a name="EntityEnhancement-Explicitjavaagentsupport"></a>Explicit javaagent
support</h5>
<p>The recommended way get runtime enhancement for the JSE environment is to provide
a javaagent when launching the JVM that OpenJPA is running in. This is a common method to
use when executing individual JUnits in a development environment because it is very painless
and easy. All that is required to get runtime enhancement is to specify the -javaagent:openjpa-all-2.2.0-SNAPSHOT.jar
(as an example) on the JVM configuration.</p>

<p>More information can be found on the <a href="/confluence/display/openjpa/Runtime+Enhancement"
title="Runtime Enhancement">Runtime Enhancement</a> page.</p>

<h5><a name="EntityEnhancement-Implicitjavaagentsupport"></a>Implicit javaagent
support</h5>
<p><a href="https://issues.apache.org/jira/browse/OPENJPA-952" class="external-link"
rel="nofollow">OPENJPA-952</a> added the capability to have OpenJPA attempt to dynamically
load the javaagent enhancer. If you see the following message, OpenJPA loaded the enhancer
dynamically.</p>
<blockquote><p>[java] 1453  jpa_app  INFO   [main] openjpa.Runtime - OpenJPA dynamically
loaded the class enhancer. Any classes that were not enhanced at build time will be enhanced
when the are loaded by the JVM.</p></blockquote>
<p>This method of enhancement is intended for first time users or developers as it has
a number of caveats.</p>
<ul>
	<li>It works with both the Sun/Oracle 1.6SDK and IBM 1.6JDK.  The JRE is not sufficient.</li>
	<li>If any unenhanced Entities are loaded by the JVM before an EntityManagerFactory
is created, this method of enhancement will not work. If this condition is encountered, you
will see the following warning:
<blockquote><p>[java] 1047  jpa_app  WARN   [main] openjpa.Enhance - Unenhanced
classes were detected even though the enhancer has ran. Ensure that the EntityManagerFactory
is created prior to creating any Entities.</p></blockquote></li>
</ul>


<p>If your application uses some other method of enhancement, this support can be explicitly
disabled by setting the following property in your persistence.xml.</p>
<blockquote><p>&lt;property name="openjpa.DynamicEnhancementAgent" value="false"/&gt;</p></blockquote>

<p><a name="EntityEnhancement-subclassing"></a></p>
<h2><a name="EntityEnhancement-SubclassingEnhancement"></a>Subclassing Enhancement</h2>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>Not Recommended</b><br
/>The use of OpenJPA's subclassing support is not recommended, and is disabled by default
in OpenJPA 2.0 and beyond.</td></tr></table></div>
<p>When running in a Java SE environment or in a non-Java EE 5 compliant container,
OpenJPA can utilize runtime subclassing enhancement. The subclassing enhancement support was
added originally as a convenience to new developers to reduce the amount of work to get a
'HelloWorld-ish' OpenJPA application working out of the box. It was never meant to run in
production. So you're probably thinking that this sounds great&#33; OpenJPA handles enhancement
automatically for me and I can stop reading this post. Wrong&#33; Subclassing has two
major drawbacks. First off, it isn't nearly as fast as byte-code enhancement and the second
drawback is that there are some documented functional problems when using the subclassing
support. The moral of the story is, don't use this method of enhancement.</p>

<p>For reference, the property that enables/disables the subclassing support is openjpa.RuntimeUnenhancedClasses.
 The value "unsupported" is the recommended and default setting for this property.</p>

<p>Additional information regarding the subclassing enhancement can be found in the
<a href="http://openjpa.apache.org/builds/latest/docs/manual/manual.html#ref_guide_pc_enhance"
class="external-link" rel="nofollow">OpenJPA docs</a>.</p>

<h2><a name="EntityEnhancement-AuthorAttribution"></a>Author Attribution</h2>

<p>The content for this page and sub-pages was adapted from content created by OpenJPA
contributor Rick Curtis from the following <a href="http://webspherepersistence.blogspot.com/"
class="external-link" rel="nofollow">WebSphere and Java Persistence</a> blog entries:<br/>
<a href="http://webspherepersistence.blogspot.com/2009/02/openjpa-enhancement.html" class="external-link"
rel="nofollow">http://webspherepersistence.blogspot.com/2009/02/openjpa-enhancement.html</a><br/>
<a href="http://webspherepersistence.blogspot.com/2009/04/openjpa-enhancement-eclipse-builder.html"
class="external-link" rel="nofollow">http://webspherepersistence.blogspot.com/2009/04/openjpa-enhancement-eclipse-builder.html</a></p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/openjpa/Entity+Enhancement">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=27090&revisedVersion=11&originalVersion=10">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/openjpa/Entity+Enhancement?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message