docs/3.0/objectcontext-memory-management.html

Title: ObjectContext Memory Management

	<H2><A name="ObjectContextMemoryManagement-MemoryManagementStrategy"></A>Memory Management Strategy</H2>

<P>Since Cayenne 3.0, by default DataContext uses weak references to store registered objects. So objects are allowed to be garbage collected by the VM if they are not referenced elsewhere in the application. &quot;Elsewhere&quot; usually means one of the following:</P>

<UL>
	<LI>An object is directly or indirectly referenced by the application.</LI>
	<LI>An object is a part of the cached query result stored by Cayenne.</LI>
	<LI>An object is &quot;dirty&quot; (i.e. new, modified or deleted). In this case Cayenne ensures that such object is retained at least until commit or rollback.</LI>
</UL>


<H2><A name="ObjectContextMemoryManagement-WhentoAvoidWeakReferences"></A>When to Avoid Weak References</H2>

<P>In some cases automatic cleaning of registered objects may result in extra DB trips later on. Depending on a situation, this may or may not be critical, so users will need to weigh the choices of fewer queries vs. smaller memory footprint. In addition to the &quot;dirty objects&quot; scenario described above (and taken care by Cayenne behind the scenes), here are a few more scenarios where a user may choose a different strategy:</P>

<UL>
	<LI>Nested DataContexts: When a child nested DataContext commits to parent, parent using weak references may have already deallocated some of the objects being committed and will have to refetch them.</LI>
	<LI>ROP: When an ROP client commits to the server, parent server DataContext using weak references may have already deallocated some of the objects being committed and will have to refetch them.</LI>
</UL>


<P>To ensure that weak references are not used, create a DataContext manually, passing a regular <TT>HashMap</TT> to the <TT>ObjectStore</TT> constructor.</P>

<P><EM>TODO: an example, and figure out how to make it a parameter in the Modeler</EM></P>