I have an integer <version> property. When I do merge(), the property gets incremented in the database, but not in the object itself. As a consequence, if I attempt to do another update using the same object, I get concurrent access exception (which is not correct).

I'm wondering if it's a feature of bug?

Feature :)

alright then. where can I read why is it done this way?

You are supposed to do:

object = merge(object)

Never keep using an object after you merge it. It is stale.

oh, yeah, now I noticed the merge() return value finally...
nevertheless, it makes my DAO layer a bit inconsistent:

void save(Foo foo); // updates PK in foo itself
...
Foo update(Foo foo); // returns a copy instead

well, thanks for pointing out to the least expected direction -- source itself ;)