1.) One of the considerations is that if we provide two or more methods that do something similar (ex. merge and update), both methods will need to be overridden when the user wants to alter the functionality. This could lead to code duplication and possible inconsistencies.
2.) In Hibernate persist() and save() have the following distinction: persist() doesn't guarantee that the identifier value will be assigned to the persistent instance immediately, the assignment might happen at flush time. save() does guarantee to return an identifier.
3.) In Hibernate the difference between update() and merge() is significant. update() will make the given object persistent and throw an error if another object with the same ID is already persistent in the Session. merge() doesn't care if another object is already persistent, but it also doesn't make the given object persistent; it just copies over the values to the datastore.
4.) "find" doesn't make the most sense to me on the remote side. "fetch" seems to describe better what's happening.
The other side is keeping things uniform with ourselves and with JPA. If the method names are the same it's easier to get up to speed and remember.
5.) I believe I prefer merge() to update(). update() can cause complicated exceptions when the same entity is already associated with the session. update() can be a hard method to override because of the necessity of keeping the same object; I've had trouble with this myself.
So we can avoid this sort of problem by using
cat = dao.merge(cat) instead of dao.update(cat)
The only hard part about this that I can think of right now is if the original cat is referenced by other entities or collections.
6.) Another consideration is that when we provide a JPA implementation it will be impossible to implement update() or save(). I wonder if we want to have an extended interface for the Hibernate implementation that also includes such methods, while keeping the common interface simpler.
An extended interface might include simply an attach() method that corresponds to saveOrUpdate(), or we could even call it saveOrUpdate() (why complicate things?).
Please comment if you have any wisdom, throughts or opinions.