This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch 3.0.0
in repository https://gitbox.apache.org/repos/asf/causeway.git
The following commit(s) were added to refs/heads/3.0.0 by this push:
new dd51890ef4 adds notes on static weaving
dd51890ef4 is described below
commit dd51890ef489816b811c1bf1c4a46715e084b8cb
Author: danhaywood <[email protected]>
AuthorDate: Sun Apr 7 16:42:25 2024 +0100
adds notes on static weaving
---
.../images/enable-static-weaving-in-IntelliJ.png | Bin 0 -> 83860 bytes
.../jpa/adoc/modules/ROOT/pages/weaving.adoc | 121 +++++++++++++++------
2 files changed, 89 insertions(+), 32 deletions(-)
diff --git
a/persistence/jpa/adoc/modules/ROOT/images/enable-static-weaving-in-IntelliJ.png
b/persistence/jpa/adoc/modules/ROOT/images/enable-static-weaving-in-IntelliJ.png
new file mode 100644
index 0000000000..f54848f6f2
Binary files /dev/null and
b/persistence/jpa/adoc/modules/ROOT/images/enable-static-weaving-in-IntelliJ.png
differ
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc
b/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc
index 62c3da1348..56159ad9d1 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/weaving.adoc
@@ -5,16 +5,70 @@
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.
-See xref:#runtime[below] for further details on how to set this up.
+With JPA, the code that performs this is "weaved" into your own domain entity
code.
+This "weaving" can be done either statically during compile-time, or
dynamically at runtime using a Java agent.
-== Configuration
-There are a number of EclipseLink configuration options to set or optionally
to be set to enable weaving:
+[#compiletime]
+== Static (Compile-time) Weaving
+
+To enable static weaving, set
xref:refguide:config:sections/eclipselink.adoc#eclipselink.weaving[eclipselink.weaving]:
+
+[source,properties]
+.application.properties
+----
+eclipselink.weaving=static
+----
+
+WARNING: The ability to set `static` as a value is currently broken in
2.0.0/3.0.0; but a fix is available in the xref:comguide::nightly-builds.adoc[].
+
+In addition, add the following to the `pom.xml` of all modules that contain
JPA entities:
+
+[source,xml]
+.pom.xml
+----
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>com.ethlo.persistence.tools</groupId>
+ <artifactId>eclipselink-maven-plugin</artifactId>
+ <version>2.7.9.1</version>
+ <executions>
+ <execution>
+ <id>weave</id>
+ <phase>process-classes</phase>
+ <goals>
+ <goal>weave</goal>
+ </goals>
+ <configuration>
+
<basePackage>domainapp.modules.simple.dom</basePackage> <!--.-->
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+<build>
+----
+<.> Update as required.
+
+And in the IDE, you may need to also configure to ensure that this weaving is
performed as necessary, for example:
+
+image::enable-static-weaving-in-IntelliJ.png[]
+
+NOTE: Thanks for the contribution via
link:https://the-asf.slack.com/archives/CFC42LWBV/p1712451654657869?thread_ts=1709070676.947439&cid=CFC42LWBV[Slack]
channel.
+
+
+[#runtime]
+== Dynamic (Runtime) Weaving
+
+
+WARNING: This is currently broken in 2.0.0/3.0.0.
+The workaround is to use xref:#compiletime[static] weaving instead.
+
+The xref:docs:starters:simpleapp.adoc[SimpleApp] and
xref:docs:starters:helloworld.adoc[HelloWorld] starter apps demonstrate the
dynamic agent approach.
-* at a minimum, set
xref:refguide:config:sections/eclipselink.adoc#eclipselink.weaving[eclipselink.weaving]:
+To enable runtime weaving, set
xref:refguide:config:sections/eclipselink.adoc#eclipselink.weaving[eclipselink.weaving]:
+
[source,properties]
.application.properties
@@ -22,6 +76,35 @@ There are a number of EclipseLink configuration options to
set or optionally to
eclipselink.weaving=true
----
+
+As well as setting the above configuration options, it's also necessary 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]
+----
+mvn dependency:fetchData -DgroupId=org.springframework
-DartifactId=spring-instrument -Dversion=XXX
+----
+=
+changing "XXX" to the value that `${spring-framework.version}` resolves to,
from the Causeway 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.
+
+
+
+== Configuration
+
+There are a number of other EclipseLink configuration options relate to
weaving:
+
* in addition, optionally set the following (their default values are shown):
+
[source,properties]
@@ -60,29 +143,3 @@
causeway.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]
-----
-mvn dependency:fetchData -DgroupId=org.springframework
-DartifactId=spring-instrument -Dversion=XXX
-----
-=
-changing "XXX" to the value that `${spring-framework.version}` resolves to,
from the Causeway 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.
-
