[Hibernate-devel] proposed API change

[Gavin_King/Cirrus%<CI...@ci...>]

In this post:

http://sourceforge.net/forum/forum.php?thread_id=722838&forum_id=128638

Yaron Zakai makes a suggestion I quite like.

I've seen that new users often have trouble realizing they need to use
insert() instead of save() when they want to use application-assigned ids.
People seem to expect that the "assigned" id generator will just use the
existing id of an object when you call save().

Secondly, some people would like insert() to cascade to insert(). Whereas
other times insert() to save() is appropriate.

So I would like to deprecate the following methods:

  Session.insert(Object)
  Session.insert(Object, Serializable)

and add the following method

  Session.save(Object, Serializable)

(which does exactly what Session.insert(Object, Serializable) used to do.)

Then we would deprecate the IDGenerator interface and replace it with:

public interface IdentifierGenerator {
  public Serializable generate(SessionImplementor session, Object entity)
    throws ..... ;
}

Then the assigned id generator would return the current value of the
entity's id property, instead of throwing an exception.

So instead of:

  session.insert(o)

you use

  session.save(o)

This would allow a save() to cascade to either an "insert" or a "save"
depending upon the id generator in use. You can still always assign your
own id (regardless of what id generator is used) by calling

  session.save(o, id)

In favor of this change:

 * it won't break any existing code
 * its more flexible
 * its more understandable to new users
 * its very easy to implement

On the downside, it requires deprecations of methods on the central API
interface, which is not something that should be done without due
consideration.

NEways this feels right to me. Opinions?