The Persistence Life Cycle - Beginning Hibernate: From Novice to Professional - page 70

All of the save() methods take a transient object reference (which must not be null) as an
argument. Hibernate expects to find a mapping for the transient object's class—Hibernate
cannot persist arbitrary unmapped objects.
When persisting an object, it is possible for the user to override the identifier value gener-
ated by Hibernate by setting the id field property or calling an alternative save() method that
also takes an object id as an argument. Obviously, this is most useful when the entity does not
have its own id field or property, but it can be used even if it does. The id must not be null,
and must be a Serializable value. If your entity uses a primitive to represent the id field, you
can use the appropriate wrapper object. For example, int identifier values can be wrapped in
java.lang.Integer objects.
The save() methods all create a new org.hibernate.event.SaveOrUpdateEvent event. We
discuss events in more detail in Appendix A, although you do not have to worry about these
implementation details to use Hibernate effectively.
At its simplest, we create a new object in Java, set a few of its properties, and then save it
through the session, as follows:
Supplier superCorp = new Supplier();
superCorp.setName("SuperCorp");
session.save(superCorp);
It is not appropriate to save an object that has already been persisted. Equally, it is not
appropriate to update a transient object. If it is impossible or inconvenient to determine the
state of the object from your application code, you may use the saveOrUpdate() method.
Hibernate uses the identifier of the object to determine whether to insert a new row into
the database or update an existing row. The method signature is as follows:
public void saveOrUpdate(Object object) throws HibernateException
Once an object is in a persistent state, Hibernate manages updates to the database itself
as you change the fields and properties of the object.
In order to support the behavior required by the new EJB 3 EntityManager , a persist()
method has been added to the API. This behaves the same as the save() methods, except it is
not guaranteed that the entities will immediately be assigned a primary key value. We discuss
EJB 3 and the EntityManager in Appendix A.
Object Equality and Identity
When we discuss persistent objects in Hibernate, we also need to consider the role that object
equality and identity plays with Hibernate. When we have a persistent object in Hibernate,
that object represents both an instance of a class in a particular Java virtual machine ( JVM)
and a row (or rows) in a database table (or tables).
Requesting a persistent object again from the same Hibernate session returns the same
Java instance of a class, which means that you can compare the objects using the standard Java
== equality syntax. If, however, you request a persistent object from more than one Hibernate
session, Hibernate will provide distinct instances from each session, and the == operator will
return false if you compare these object instances.
Taking this into account, if you are comparing objects in two different sessions, you will
need to implement the equals() method on your Java persistence objects.