HHH-9809 - Improve Hibernate Gradle plugin

Author: sebersole

documentation/src/main/asciidoc/topical/bytecode/BytecodeEnhancement.adoc

@@ -0,0 +1,93 @@
+= Bytecode Enhancement
+:toc:
+
+This guide covers Hibernate's ability to enhance an applications domain model, the ways to perform that
+enhancement and the capabilities introduced into the domain model by the enhancement.
+
+
+== The capabilities
+
+Hibernate will enhance the classes in an application's domain model in order to add one or more of the
+following capabilities:
+
+    . Lazy state initialization
+    . Dirtiness tracking
+    . Automatic bi-directional association management
+    . Performance optimizations
+
+todo : explain each in detail
+
+
+== Performing enhancement
+
+Ultimately all enhancement is handled by the `org.hibernate.bytecode.enhance.spi.Enhancer` 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.
+
+=== Run-time enhancement
+
+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.  In this
+scenario, run-time enhancement can be enabled by specifying `hibernate.ejb.use_class_enhancer=true` as a
+persistent unit property.
+
+
+=== Build-time enhancement
+
+Hibernate also offers the ability to integrate the enhancement of the domain model as part of the
+normal build cycle of that domain model.  Gradle, Ant and Maven are all supported.  One possible benefit
+of this approach is that the enhanced classes are what gets added to the jar and can then be used on both
+sides of serialization.
+
+
+=== Gradle Plugin
+
+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:
+
+[[gradle-plugin-apply-example]]
+.Apply the plugin
+====
+[source, GROOVY]
+----
+ext {
+  hibernateVersion = 'hibernate-version-you-want'
+}
+buildscript {
+  dependencies {
+    classpath "org.hibernate:hibernate-gradle-plugin:$hibernateVersion"
+  }
+}
+----
+====
+
+At the moment there is not much to configure with regard to the Enhancer, but what is configurable is exposed
+through a DSL extension registered.  By default enhancement will not be done (in preparation for when this
+Gradle plugin offers additional capabilities).  To enable it you must configure the following DSL extension:
+
+[[gradle-plugin-apply-example]]
+.Apply the plugin
+====
+[source, GROOVY]
+----
+hibernate {
+  enhance {
+    // any configuration goes here
+  }
+}
+----
+====
+
+Currently the "enhance" extension supports 3 properties:
+
+    * `enableLazyInitialization`
+    * `enableDirtyTracking`
+    * `enableAssociationManagement`
+
+Once enhancement overall is enabled, the default for these 3 properties is `true`.
+
+
+=== Ant Task
+
+
+=== Maven Plugin

documentation/src/main/asciidoc/topical/index.adoc

@@ -19,6 +19,7 @@ NOTE: This is still very much a work in progress. <<helping,Help>> is definitely
 == Tooling
 
 * See the <<metamodelgen/MetamodelGenerator.adoc#,Metamodel Generator Guide>> for details on generating a JPA "Static Metamodel"
+* see the <<bytecode/BytecodeEnhancement.adoc#,Bytecode Enhancement Guide>> for information on bytecode enhancement
 * Guide on the Gradle plugin coming soon
 * Guide on the Ant tasks coming soon
 * Guide on the Maven plugin coming soon

tooling/hibernate-gradle-plugin/README.md

@@ -0,0 +1,6 @@
+Defines a Gradle plugin for introducing Hibernate specific tasks and capabilities into and end-user build.
+
+Currently the only capability added is for bytecode enhancement of the user domain model, although other capabilities are 
+planned.
+
+todo : usage

tooling/hibernate-gradle-plugin/hibernate-gradle-plugin.gradle

@@ -4,19 +4,21 @@
  * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
+apply plugin: 'java-gradle-plugin'
+
 apply plugin: 'groovy'
 apply plugin: 'maven'
 apply plugin: 'java'
 
 dependencies {
-   compile( project(':hibernate-core') ) 
-   compile( libraries.jpa )
-   compile( libraries.javassist )
-   compile gradleApi()
-   compile localGroovy()
+	compile( project( ':hibernate-core' ) )
+	compile( libraries.jpa )
+	compile( libraries.javassist )
+	compile gradleApi()
+	compile localGroovy()
 }
 
 mavenPom {
-   name = 'Hibernate Gradle plugin'
-   description = "Gradle plugin for integrating Hibernate functionality into your build"
+	name = 'Hibernate Gradle plugin'
+	description = "Gradle plugin for integrating Hibernate functionality into your build"
 }

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

@@ -0,0 +1,23 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.orm.tooling.gradle
+
+/**
+ * Gradle DSL extension for configuring various Hibernate bytecode enhancement.  Registered
+ * under "hibernate.enhance".
+ *
+ * @author Steve Ebersole
+ */
+class EnhanceExtension {
+	def boolean enableLazyInitialization = true
+	def boolean enableDirtyTracking = true
+	def boolean enableAssociationManagement = true
+
+	boolean shouldApply() {
+		return enableLazyInitialization || enableDirtyTracking || enableAssociationManagement;
+	}
+}

tooling/hibernate-gradle-plugin/src/main/groovy/org/hibernate/tooling/gradle/EnhancerTask.groovy renamed to tooling/hibernate-gradle-plugin/src/main/groovy/org/hibernate/orm/tooling/gradle/EnhancerTask.groovy

@@ -4,7 +4,7 @@
  * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
-package org.hibernate.tooling.gradle
+package org.hibernate.orm.tooling.gradle
 
 import javax.persistence.ElementCollection
 import javax.persistence.Entity

tooling/hibernate-gradle-plugin/src/main/groovy/org/hibernate/orm/tooling/gradle/HibernateExtension.groovy

@@ -0,0 +1,53 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.orm.tooling.gradle
+
+import org.gradle.api.Project
+import org.gradle.api.plugins.JavaPluginConvention
+import org.gradle.api.tasks.SourceSet
+import org.gradle.util.ConfigureUtil
+
+/**
+ * Gradle DSL extension for configuring various Hibernate built-time tasks.  Registered
+ * under "hibernate".
+ *
+ * @author Steve Ebersole
+ */
+class HibernateExtension {
+	private final Project project
+
+	/**
+	 * The source sets that hold persistent model.  Default is project.sourceSets.main
+	 */
+	def SourceSet[]  sourceSets
+	/**
+	 * Configuration for bytecode enhancement.  Private; see instead {@link #enhance(groovy.lang.Closure)}
+	 */
+	protected EnhanceExtension enhance
+
+	HibernateExtension(Project project) {
+		this.project = project
+		this.sourceSet( project.getConvention().getPlugin( JavaPluginConvention ).sourceSets.main )
+	}
+
+	/**
+	 * Add a single SourceSet.
+	 *
+	 * @param sourceSet The SourceSet to add
+	 */
+	void sourceSet(SourceSet sourceSet) {
+		if ( sourceSets == null ) {
+			sourceSets = []
+		}
+		sourceSets += sourceSets
+	}
+
+	void enhance(Closure closure) {
+		enhance = new EnhanceExtension()
+		ConfigureUtil.configure( closure, enhance )
+	}
+}