Automatic state detection

Hibernate users have requested a general purpose method that either saves a transient instance by generating a new identifier or updates/reattaches the detached instances associated with its current identifier. The saveOrUpdate() method implements this functionality.

// in the first session
Cat cat = (Cat) firstSession.load(Cat.class, catID);
// in a higher tier of the application
Cat mate = new Cat();
cat.setMate(mate);
// later, in a new session
secondSession.saveOrUpdate(cat);   // update existing state (cat has a non-null id)
secondSession.saveOrUpdate(mate);  // save the new instance (mate has a null id)

The usage and semantics of saveOrUpdate() seems to be confusing for new users. Firstly, so long as you are not trying to use instances from one session in another new session, you should not need to use update(), saveOrUpdate(), or merge(). Some whole applications will never use either of these methods.

Usually update() or saveOrUpdate() are used in the following scenario:

• the application loads an object in the first session

• the object is passed up to the UI tier

• some modifications are made to the object

• the object is passed back down to the business logic tier

• the application persists these modifications by calling update() in a second session

saveOrUpdate() does the following:

• if the object is already persistent in this session, do nothing

• if another object associated with the session has the same identifier, throw an exception

• if the object has no identifier property, save() it

• if the object's identifier has the value assigned to a newly instantiated object, save() it

• if the object is versioned (by a <version> or <timestamp>), and the version property value is the same value assigned to a newly instantiated object, save() it

• otherwise update() the object

and merge() is very different:

• if there is a persistent instance with the same identifier currently associated with the session, copy the state of the given object onto the persistent instance

• if there is no persistent instance currently associated with the session, try to load it from the database, or create a new persistent instance

• the persistent instance is returned

• the given instance does not become associated with the session, it remains detached