deprecate old Session methods

[gavinking]

I think we should consider deprecating the following methods of Session:

• saveOrUpdate() and update(), and save(), and
• load().

The update() and saveOrUpdate() operations were, essentially, a failed experiment from early in the history of Hibernate, and were replaced by merge() in the JPA spec. It seems clear to me that users have had many fewer problems with merge() than with update(), and I think we probably should have deprecated these operations long ago.

The save() operation is almost identical to saveOrUpdate() except that it returns an id. You can use it like persist(), but I think persist() is a better name anyway.

The load() method was the first (historical) way to load an entity by id. It was originally defined to be lazy, which turned out to be annoying and confusing for users most of the time (but sometimes useful). So we added the get() method which is defined to be eager. Unfortunately, the names of these operations were always pretty confusing: it would make more sense if they exactly reversed. Furthermore, load() comes with overloads which accept LockModes, which really don't make sense if the concept of the thing is supposed to be laziness.

So in JPA these operations were named getReference() and find() respectively, and only find() accepts LockModes. I think it's clear that getReference() is a much, much better name than load(). On the other hand, I don't think find() is a better name than get().

So I think we could reasonably deprecate load(), and leave get() unmolested.

[gavinking]

Another one to consider here is remove() vs delete(). I'm not sure if it matters much.

[beikov]

+1 for dropping delete()

[sebersole]

I completely agree with dropping

• #save - #persist is a much better API/semantic
• #saveOrUpdate - #merge is a much better API/semantic

I like the idea of dropping #load (not deprecating) and leaving #get for all of the reasons you mention.

I'm not so sure about #update though. I have to think about that one.

[beikov]

save, saveOrUpdate and update all fire a SaveOrUpdateEvent so it seems to me, these methods all do the same if you ignore the different listener groups that are being invoked but usually contain the same listeners. Not sure how this is different from merge() but the code in DefaultSaveOrUpdateEventListener looks very different from DefaultMergeEventListener, so if you say merge() is enough/better, I'm +1 for removing the saveOrUpdate code. I never used that before to be honest, so I don't know much about it.

+1 for dropping load()

[sebersole]

The difference with update versus merge is the fact that it is the same object graph, not a copy. It is a true re-attach API

[gavinking]

Right, the difference is that update() has the potential to suddenly throw an already-attached exception randomly and unexpectedly.

[sebersole]

Not speaking to its usefulness. Just explaining the distinction for Christian

[gavinking]

See #4590