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.