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 <d...@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.
+
