[isis] 07/10: ISIS-3161: improves docs for JPA weaving

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to tag saveit
in repository https://gitbox.apache.org/repos/asf/isis.git

commit 1b713861fd0fa27c07cadb6d975c3260ee2a4e9a
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Aug 29 10:53:33 2022 +0100

    ISIS-3161: improves docs for JPA weaving
---
 .../jpa/adoc/modules/ROOT/pages/weaving.adoc       | 76 +++++++++++++++++++++-
 1 file changed, 73 insertions(+), 3 deletions(-)

diff --git a/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc b/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc
index b65d86d6c8..41527e8302 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc
@@ -6,13 +6,83 @@
 A responsibility of all ORMs is lazy loading of related objects (so as not to load all the data in one go), and tracking of objects as they are modified (to flush back to the database).
 
 With JPA, this is typically done dynamically at runtime, using a Java agent.
-The xref:docs:starters:simpleapp.adoc[SimpleApp] and xref:docs:starters:helloworld.adoc[HelloWorld] starter apps demonstrate this, describing how to obtain the required `spring-instrument.jar` file.
+The xref:docs:starters:simpleapp.adoc[SimpleApp] and xref:docs:starters:helloworld.adoc[HelloWorld] starter apps demonstrate this.
+See xref:#runtime[below] for further details on how to set this up.
 
-To run, use:
 
+== Configuration
+
+There are a number of EclipseLink configuration options to set or optionally to be set to enable weaving:
+
+* at a minimum, set xref:refguide:config:sections/eclipselink.adoc#eclipselink.weaving[eclipselink.weaving]:
++
+[source,properties]
+.application.properties
+----
+eclipselink.weaving=true
+----
+
+* in addition, optionally set the following (their default values are shown):
++
+[source,properties]
+.application.properties
+----
+eclipselink.weaving.changetracking=true
+eclipselink.weaving.eager=false
+eclipselink.weaving.fetchgroups=true
+eclipselink.weaving.internal=true
+eclipselink.weaving.lazy=true
+----
++
+These all default to `true` except for xref:refguide:config:sections/eclipselink.adoc#eclipselink.weaving.eager[eclipselink.weaving.eager], which you should only enable if you fully understand its consequences.
+
+The weaving process modifies the classes themselves, introducing additional `public` methods.
+Depending upon the value of xref:refguide:config:sections/isis.core.meta-model.introspector.adoc#isis.core.meta-model.introspector.policy[isis.core.meta-model.introspector.policy] configuration property, these could be picked up as part of the framework's metamodel, which is not what you want.
+
+Therefore, to use JPA, you will also need to change this configuration property, either:
+
+* to xref:refguide:applib:index/annotation/Introspection.adoc#ANNOTATION_REQUIRED[IntrospectionPolicy.ANNOTATION_REQUIRED]
++
+[source,properties]
+.application.properties
+----
+isis.core.meta-model.introspector.policy=annotation_required
+----
++
+or,
+
+* to xref:refguide:applib:index/annotation/Introspection.adoc#ENCAPSULATION_ENABLED[IntrospectionPolicy.ENCAPSULATION_ENABLED]
++
+[source,properties]
+.application.properties
+----
+isis.core.meta-model.introspector.policy=encapsulation_enabled
+----
+
+The xref:docs:starters:simpleapp.adoc[SimpleApp] and xref:docs:starters:helloworld.adoc[HelloWorld] starter apps both use the latter option.
+
+[#runtime]
+== Runtime
+
+As well as setting the above configuration options, it's also neceesary to run the application with the `spring-instrument.jar` Java agent, which actually performs the weaving at load-time.
+
+* Download this jar file using:
++
 [source,bash]
 ----
--javaagent:lib/spring-instrument.jar
+mvn dependency:get -DgroupId=org.springframework -DartifactId=spring-instrument -Dversion=XXX
 ----
+=
+changing "XXX" to the value that `${spring-framework.version}` resolves to, from the Isis parent `pom.xml`.
 
+* Move and rename this file, eg to `lib/spring-instrument.jar`.
+
+* Run the application using:
++
+[source,bash]
+----
+-javaagent:lib/spring-instrument.jar
+----
++
 as a JVM option.
+