Mailing-List: contact open-jpa-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: open-jpa-dev@incubator.apache.org
Received-SPF: pass (herse.apache.org: local policy)
Message-ID: <455B9A26.8080101@mousetech.com>
Date: Wed, 15 Nov 2006 17:52:22 -0500
From: Tim Holloway <timh@mousetech.com>
User-Agent: Thunderbird 1.5.0.8 (X11/20061025)
MIME-Version: 1.0
To: open-jpa-dev@incubator.apache.org
Subject: Documentation: re-attaching objects
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

First off: Is there an easy way to get the docs rendered in PDF format? 
Preferably duplex-sensitive?

Speaking of which: I got burned on this a few months back trying out 
JDO2. It looks like the same behavior applies to JPA, and considering 
the time it cost me, I'd like to see something in the docs. Here goes:

It's not uncommon in a webapp to detach an object from its persistence 
manager, then later come back and re-attach it in order to pick up 
details that weren't part of the original fetch set. A classic case of 
this is drilling down a parent-child relationship.

Consider the case where a detached parent object (P) is called upon to 
make available a collection of unfetched child objects (C) using simple 
object access (e.g. "p.getC()"). To re-attach P, I invoke the 
EntityManager merge() method.

OK, stop right there. "merge" is a doubly-unfortunate usage.

First, because in this particular instance, I don't actually want any 
unintended changes to P to leak back to the persistent copy, since in 
the case in question, I'm hoping to get read-only access, and any 
conflicts would thus hopefully throw an exception. In fact, in many 
cases, even having out-of-band changes to the persistent data coming 
back into P might be something I'd want to know about.

Fine. I want too much. So be it. I'll just have to be more careful.

A more serious objection is that "merge" isn't truly a merge. The merge 
function does not operate in-place on the object passed to it; it 
creates a whole new object based on the results of the merge operation. 
On odd Tuesdays I can recall why that must be, but intuitively, I tend 
to want the original object to be re-attached, not get dealt an entirely 
new object. Among other things, if I'm selectively fleshing out a domain 
model tree, it can really shred the graph integrity if I've got oddball 
references to the original object in various places.

Anyway, if I've grossly missed the point, please (gently) set me 
straight. But since I've obviously got a habit of this sort of 
malfeasance, I'd be very grateful if the documentation spent some extra 
time on the topic.