= Weaving

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


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.


== 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/causeway.core.meta-model.introspector.adoc#causeway.core.meta-model.introspector.policy[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 xref:refguide:applib:index/annotation/Introspection.adoc#ANNOTATION_REQUIRED[IntrospectionPolicy.ANNOTATION_REQUIRED]
+
[source,properties]
.application.properties
----
causeway.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
----
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:get -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.

