Weaving

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, 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.

Static (Compile-time) Weaving

To enable static weaving, set eclipselink.weaving:

application.properties

eclipselink.weaving=static

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 Nightly Builds.

In addition, add the following to the pom.xml of all modules that contain JPA entities:

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> (1)
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
<build>

1	Update as required.

And in the IDE, you may need to also configure to ensure that this weaving is performed as necessary, for example:

Thanks for the contribution via Slack channel.

Dynamic (Runtime) Weaving

This is currently broken in 2.0.0/3.0.0. The workaround is to use static weaving instead.

The SimpleApp and HelloWorld starter apps demonstrate the dynamic agent approach.

To enable runtime weaving, set eclipselink.weaving:

application.properties

eclipselink.weaving=true

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:
```
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:
```
-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):
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 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 causeway.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 IntrospectionPolicy.ANNOTATION_REQUIRED
application.properties
```
causeway.core.meta-model.introspector.policy=annotation_required
```
or,

to IntrospectionPolicy.ENCAPSULATION_ENABLED

application.properties

causeway.core.meta-model.introspector.policy=encapsulation_enabled

The SimpleApp and HelloWorld starter apps both use the latter option.