Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-10359 - Have consistent configuration of bytecode enhancement

This commit is contained in:
barreiro 2015-12-05 05:59:15 +00:00 committed by Steve Ebersole
parent d5740b00eb
commit 1590ad145b
11 changed files with 138 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
documentation/src/main/asciidoc/topical/bytecode/BytecodeEnhancement.adoc
View File

@ -83,7 +83,7 @@ Currently the "enhance" extension supports 4 properties:
* `enableLazyInitialization` * `enableLazyInitialization`
* `enableDirtyTracking` * `enableDirtyTracking`
* `enableAssociationManagement` * `enableAssociationManagement`
* `enableFieldAccessEnhancement` * `enableExtendedEnhancement`
Once enhancement overall is enabled, the default for the first 3 properties is `true`. Field access is not enhanced by Once enhancement overall is enabled, the default for the first 3 properties is `true`. Field access is not enhanced by
default, as it can potentially trigger enhancement of code outside the entities, and also because it assumes that all default, as it can potentially trigger enhancement of code outside the entities, and also because it assumes that all
@ -102,7 +102,7 @@ on the plugin are:
* `enableLazyInitialization` * `enableLazyInitialization`
* `enableDirtyTracking` * `enableDirtyTracking`
* `enableAssociationManagement` * `enableAssociationManagement`
* `enableFieldAccessEnhancement` * `enableExtendedEnhancement`
Field access is not enhanced by default, because it can potentially trigger enhancement of code outside the entities. Field access is not enhanced by default, because it can potentially trigger enhancement of code outside the entities.
Other capabilities are enabled by default. Even if the plugin is enabled, the bytecode enhancement can be bypassed by Other capabilities are enabled by default. Even if the plugin is enabled, the bytecode enhancement can be bypassed by
@ -133,7 +133,7 @@ already in use. The XML snippet below is an example of how to declare and config
<enableLazyInitialization>true</enableLazyInitialization> <enableLazyInitialization>true</enableLazyInitialization>
<enableDirtyTracking>true</enableDirtyTracking> <enableDirtyTracking>true</enableDirtyTracking>
<enableAssociationManagement>true</enableAssociationManagement> <enableAssociationManagement>true</enableAssociationManagement>
<enableFieldAccessEnhancement>false</enableFieldAccessEnhancement> <enableExtendedEnhancement>false</enableExtendedEnhancement>
</configuration> </configuration>
<goals> <goals>
<goal>enhance</goal> <goal>enhance</goal>

85
documentation/src/main/docbook/userGuide/en-US/chapters/enhancement/BytecodeEnhancement.xml
View File

@ -138,33 +138,10 @@
<section> <section>
<title>Performing enhancement</title> <title>Performing enhancement</title>
<section>
<title>Run-time enhancement</title>
<para> <para>
Currently run-time enhancement of the domain model is only supported in managed JPA There are two methods to perform bytecode enhancement. It can be done during run time or build time,
environments following the JPA defined SPI for performing class transformations. Even then, this using one of the provided plugins for build automation tools. Each capability must be enabled
support is disabled by default. To enable run-time enhancement, specify independently, using the respective property:
<property>hibernate.ejb.use_class_enhancer=true</property> as a persistent unit property.
</para>
<para>
Also, at the moment only annotated classes are supported for run-time enhancement
</para>
</section>
<section>
<title>Gradle plugin</title>
<para>
Hibernate provides a Gradle plugin that is capable of providing build-time enhancement of the
domain model as they are compiled as part of a Gradle build. To use the plugin a project would
first need to apply it:
</para>
<example>
<title>Apply the Gradle plugin</title>
<programlisting role="JAVA"><xi:include href="extras/gradle-example.gradle" parse="text"/></programlisting>
</example>
<para>
The configuration that is available is exposed through a registered Gradle DSL extension:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>enableLazyInitialization</term> <term>enableLazyInitialization</term>
@ -191,10 +168,54 @@
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
The default value for all 3 configuration settings is <literal>true</literal>
</para> </para>
<para> <para>
The <code>enhance { }</code> block is required in order for enhancement to occur; enhancement Ultimately all enhancement is handled by the <code>org.hibernate.bytecode.enhance.spi.Enhancer</code> class.
Custom means to enhancement can certainly be crafted on top of Enhancer, but that is beyond the scope of
this guide. Here we will focus on the means Hibernate already exposes for performing these enhancements.
</para>
<section>
<title>Run-time enhancement</title>
<para>
Currently run-time enhancement of the domain model is only supported in managed JPA
environments following the JPA defined SPI for performing class transformations. Even then, this
support is disabled by default. To enable run-time enhancement, turn on one or more of the following
properties in the persistent unit:
<example>
<title>Example persistence.xml</title>
<programlisting role="XML"><xi:include href="extras/persistence-example.xml" parse="text"/></programlisting>
</example>
</para>
<para>
Also, at the moment only annotated classes are supported for run-time enhancement. Only the
classes declared in the persistent unit will be enhanced.
</para>
</section>
<section>
<title>Build-time enhancement</title>
<para>
Hibernate provides plugins for Gradle and Maven build tools.
</para>
<section>
<title>Gradle plugin</title>
<para>
Hibernate provides a Gradle plugin that is capable of providing build-time enhancement of the
domain model as they are compiled as part of a Gradle build. To use the plugin a project would
first need to apply it.
</para>
<example>
<title>Apply the Gradle plugin</title>
<programlisting role="JAVA"><xi:include href="extras/gradle-example.gradle" parse="text"/></programlisting>
</example>
<para>
The configuration that is available is exposed through a registered Gradle DSL extension. The default
value for all configuration settings is <literal>false</literal>.
</para>
<para>
The <code>enhance { }</code> block is required in order for enhancement to occur. Enhancement
is disabled by default in preparation for additions capabilities (hbm2ddl, etc) in the plugin. is disabled by default in preparation for additions capabilities (hbm2ddl, etc) in the plugin.
</para> </para>
</section> </section>
@ -203,8 +224,8 @@
<title>Maven plugin</title> <title>Maven plugin</title>
<para> <para>
Hibernate provides a Maven plugin capable of providing build-time enhancement of the Hibernate provides a Maven plugin capable of providing build-time enhancement of the
domain model as they are compiled as part of a Maven build. See the section on the Gradle plugin domain model as they are compiled as part of a Maven build. The configuration has the same properties
for details on the configuration settings. Again, the default for those 3 is <literal>true</literal>. as the Gradle plugin and the default value for all settings is also <literal>false</literal>.
</para> </para>
<para> <para>
The Maven plugin supports one additional configuration settings: failOnError, which controls The Maven plugin supports one additional configuration settings: failOnError, which controls
@ -213,10 +234,10 @@
</para> </para>
<example> <example>
<title>Apply the Maven plugin</title> <title>Apply the Maven plugin</title>
<programlisting role="JAVA"><xi:include href="extras/maven-example.pom" parse="text"/></programlisting> <programlisting role="XML"><xi:include href="extras/maven-example.pom" parse="text"/></programlisting>
</example> </example>
</section> </section>
</section>
</section> </section>
</chapter> </chapter>

6
documentation/src/main/docbook/userGuide/en-US/chapters/enhancement/extras/gradle-example.gradle
View File

@ -1,5 +1,5 @@
ext { ext {
hibernateVersion = 'hibernate-version-you-want' hibernateVersion = 'x.y.z.Final'
} }
buildscript { buildscript {
@ -10,6 +10,8 @@ buildscript {
hibernate { hibernate {
enhance { enhance {
// any configuration goes here enableLazyInitialization= false
enableDirtyTracking = false
enableAssociationManagement = false
} }
} }

8
documentation/src/main/docbook/userGuide/en-US/chapters/enhancement/extras/maven-example.pom
View File

@ -4,14 +4,14 @@
<plugin> <plugin>
<groupId>org.hibernate.orm.tooling</groupId> <groupId>org.hibernate.orm.tooling</groupId>
<artifactId>hibernate-enhance-maven-plugin</artifactId> <artifactId>hibernate-enhance-maven-plugin</artifactId>
<version>$currentHibernateVersion</version> <version>$hibernateVersion</version>
<executions> <executions>
<execution> <execution>
<configuration> <configuration>
<failOnError>true</failOnError> <failOnError>true</failOnError>
<enableLazyInitialization>true</enableLazyInitialization> <enableLazyInitialization>false</enableLazyInitialization>
<enableDirtyTracking>true</enableDirtyTracking> <enableDirtyTracking>false</enableDirtyTracking>
<enableAssociationManagement>true</enableAssociationManagement> <enableAssociationManagement>false</enableAssociationManagement>
</configuration> </configuration>
<goals> <goals>
<goal>enhance</goal> <goal>enhance</goal>

11
documentation/src/main/docbook/userGuide/en-US/chapters/enhancement/extras/persistence-example.xml Normal file
View File

@ -0,0 +1,11 @@
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
<persistence-unit name="Example">
[...]
<properties>
[...]
<property name="hibernate.enhancer.enableLazyInitialization" value="false"/>
<property name="hibernate.enhancer.enableDirtyTracking" value="false"/>
<property name="hibernate.enhancer.enableAssociationManagement" value="false"/>
</properties>
</persistence-unit>
</persistence>

18
tooling/hibernate-enhance-maven-plugin/src/main/java/org/hibernate/orm/tooling/maven/MavenEnhancePlugin.java
View File

@ -56,22 +56,22 @@ public class MavenEnhancePlugin extends AbstractMojo {
private List<File> sourceSet = new ArrayList<File>(); private List<File> sourceSet = new ArrayList<File>();
@Parameter(property = "dir", defaultValue = "${project.build.outputDirectory}") @Parameter(property = "dir", defaultValue = "${project.build.outputDirectory}")
private String dir = null; private String dir;
@Parameter(property = "failOnError", defaultValue = "true") @Parameter(property = "failOnError", defaultValue = "true")
private boolean failOnError = true; private boolean failOnError = true;
@Parameter(property = "enableLazyInitialization", defaultValue = "true") @Parameter(property = "enableLazyInitialization", defaultValue = "false")
private boolean enableLazyInitialization = true; private boolean enableLazyInitialization;
@Parameter(property = "enableDirtyTracking", defaultValue = "true") @Parameter(property = "enableDirtyTracking", defaultValue = "false")
private boolean enableDirtyTracking = true; private boolean enableDirtyTracking;
@Parameter(property = "enableAssociationManagement", defaultValue = "true") @Parameter(property = "enableAssociationManagement", defaultValue = "false")
private boolean enableAssociationManagement = true; private boolean enableAssociationManagement;
@Parameter(property = "enableExtendedEnhancement", defaultValue = "false") @Parameter(property = "enableExtendedEnhancement", defaultValue = "false")
private boolean enableExtendedEnhancement = false; private boolean enableExtendedEnhancement;
private boolean shouldApply() { private boolean shouldApply() {
return enableLazyInitialization || enableDirtyTracking || enableAssociationManagement || enableExtendedEnhancement; return enableLazyInitialization || enableDirtyTracking || enableAssociationManagement || enableExtendedEnhancement;
@ -79,7 +79,7 @@ public class MavenEnhancePlugin extends AbstractMojo {
public void execute() throws MojoExecutionException, MojoFailureException { public void execute() throws MojoExecutionException, MojoFailureException {
if ( !shouldApply() ) { if ( !shouldApply() ) {
getLog().info( "Skipping Hibernate enhancement plugin execution since there is no feature enabled" ); getLog().warn( "Skipping Hibernate bytecode enhancement plugin execution since no feature is enabled" );
return; return;
} }

10
tooling/hibernate-enhance-maven-plugin/src/main/resources/META-INF/maven/org.hibernate.orm.tooling/hibernate-enhance-maven-plugin/plugin-help.xml
View File

@ -67,7 +67,7 @@
<description>Enable enhancement for management of bi-direction associations</description> <description>Enable enhancement for management of bi-direction associations</description>
</parameter> </parameter>
<parameter> <parameter>
<name>enableFieldAccessEnhancement</name> <name>enableExtendedEnhancement</name>
<type>java.lang.Boolean</type> <type>java.lang.Boolean</type>
<required>false</required> <required>false</required>
<editable>true</editable> <editable>true</editable>
@ -77,10 +77,10 @@
<configuration> <configuration>
<dir>${project.build.outputDirectory}</dir> <dir>${project.build.outputDirectory}</dir>
<failOnError>true</failOnError> <failOnError>true</failOnError>
<enableLazyInitialization>true</enableLazyInitialization> <enableLazyInitialization>false</enableLazyInitialization>
<enableDirtyTracking>true</enableDirtyTracking> <enableDirtyTracking>false</enableDirtyTracking>
<enableAssociationManagement>true</enableAssociationManagement> <enableAssociationManagement>false</enableAssociationManagement>
<enableFieldAccessEnhancement>false</enableFieldAccessEnhancement> <enableExtendedEnhancement>false</enableExtendedEnhancement>
</configuration> </configuration>
</mojo> </mojo>
</mojos> </mojos>

7
tooling/hibernate-enhance-maven-plugin/src/main/resources/META-INF/maven/plugin.xml
View File

@ -79,9 +79,10 @@
<configuration> <configuration>
<dir>${project.build.outputDirectory}</dir> <dir>${project.build.outputDirectory}</dir>
<failOnError>true</failOnError> <failOnError>true</failOnError>
<enableLazyInitialization>true</enableLazyInitialization> <enableLazyInitialization>false</enableLazyInitialization>
<enableDirtyTracking>true</enableDirtyTracking> <enableDirtyTracking>false</enableDirtyTracking>
<enableAssociationManagement>true</enableAssociationManagement> <enableAssociationManagement>false</enableAssociationManagement>
<enableExtendedEnhancement>false</enableExtendedEnhancement>
</configuration> </configuration>
</mojo> </mojo>
</mojos> </mojos>

10
tooling/hibernate-gradle-plugin/src/main/groovy/org/hibernate/orm/tooling/gradle/EnhanceExtension.groovy
View File

@ -13,12 +13,12 @@ package org.hibernate.orm.tooling.gradle
* @author Steve Ebersole * @author Steve Ebersole
*/ */
class EnhanceExtension { class EnhanceExtension {
def boolean enableLazyInitialization = true def boolean enableLazyInitialization = false
def boolean enableDirtyTracking = true def boolean enableDirtyTracking = false
def boolean enableAssociationManagement = true def boolean enableAssociationManagement = false
def boolean enableFieldAccessEnhancement = false def boolean enableExtendedEnhancement = false
boolean shouldApply() { boolean shouldApply() {
return enableLazyInitialization || enableDirtyTracking || enableAssociationManagement || enableFieldAccessEnhancement; return enableLazyInitialization || enableDirtyTracking || enableAssociationManagement || enableExtendedEnhancement;
} }
} }

5
tooling/hibernate-gradle-plugin/src/main/groovy/org/hibernate/orm/tooling/gradle/HibernatePlugin.java
View File

@ -69,6 +69,7 @@ public class HibernatePlugin implements Plugin<Project> {
private void applyEnhancement(final Project project, final HibernateExtension hibernateExtension) { private void applyEnhancement(final Project project, final HibernateExtension hibernateExtension) {
if ( !hibernateExtension.enhance.shouldApply() ) { if ( !hibernateExtension.enhance.shouldApply() ) {
project.getLogger().warn( "Skipping Hibernate bytecode enhancement since no feature is enabled" );
return; return;
} }
@ -112,11 +113,11 @@ public class HibernatePlugin implements Plugin<Project> {
@Override @Override
public boolean doExtendedEnhancement(CtClass classDescriptor) { public boolean doExtendedEnhancement(CtClass classDescriptor) {
return hibernateExtension.enhance.getEnableFieldAccessEnhancement(); return hibernateExtension.enhance.getEnableExtendedEnhancement();
} }
}; };
if ( hibernateExtension.enhance.getEnableFieldAccessEnhancement() ) { if ( hibernateExtension.enhance.getEnableExtendedEnhancement() ) {
logger.warn( "Extended enhancement is enabled. Classes other than entities may be modified. You should consider access the entities using getter/setter methods and disable this property. Use at your own risk." ); logger.warn( "Extended enhancement is enabled. Classes other than entities may be modified. You should consider access the entities using getter/setter methods and disable this property. Use at your own risk." );
} }

2
tooling/hibernate-gradle-plugin/src/test/groovy/org/hibernate/orm/tooling/gradle/HibernatePluginTest.groovy
View File

@ -35,7 +35,7 @@ class HibernatePluginTest {
enableLazyInitialization = true enableLazyInitialization = true
enableDirtyTracking = true enableDirtyTracking = true
enableAssociationManagement = false enableAssociationManagement = false
enableFieldAccessEnhancement = false enableExtendedEnhancement = false
} }
} }
} }