3.5 Creating an Object
After a PersistenceManager has been retrieved, it is possible to actually begin a transaction and do something interesting with the datastore. To begin a transaction, get the current Transaction instance from the PersistenceManager:
public Transaction currentTransaction()
And call the begin() method on Transaction to start a datastore transaction:
public void begin()
Typically, any interaction with a datastore is done within the context of a transaction. A transaction simply marks the beginning and end of a unit of work, whereby all changes made either happen or do not happen.
A transaction is also the mechanism that a datastore uses to enforce concurrency control between multiple applications accessing the datastore at the same time. Not all datastores support concurrent access, but those that do ensure that each ongoing transaction is isolated from the others. For more details on concurrency control and transactions, see Section 3.14.
Instances of persistence-capable classes can now be created and made persistent. They are constructed in the same manner as normal Java and, once constructed, need to be passed to the makePersistent() method on PersistenceManager to notify the JDO implementation that the instances need to be persisted:
public void makePersistent(Object pc)
The instances won't actually be stored in the datastore until the transaction is committed, which is done using the commit() method on Transaction:
public void commit()
Alternatively, a transaction can be rolled backin this case, the instances won't become persistent and won't be stored in the datastore. This can be done using the rollback() method on Transaction, instead of commit():
public void rollback()
The following code snippet taken from CreateExample.java shows how to create an instance of the Author class and make it persistent in the datastore:
Transaction tx = pm.currentTransaction(); tx.begin(); Author author = new Author("Keiron McCammon"); pm.makePersistent(author); tx.commit();
When they are successfully committed, the fields of the new Author instance are stored in the datastore, and the in-memory instance becomes what is termed "hollow." This means that its fields are cleared so that when the instance is used in the next transaction, they will be retrieved again from the datastore.
JDO defines a number of lifecycle states for persistent objects ("hollow" being one of them). These states are used by the JDO implementation to manage the in-memory persistent objects. While it is not necessary to really understand the JDO object lifecycle (it's of primary concern only to the JDO implementation), an appreciation of what happens under the covers is always a good idea. See Section 3.13 for more details.
Not every instance that needs to be persistent has to be passed to makePersistent(). JDO defines that any instance of a persistence-capable class that is reachable from a persistent object automatically becomes persistent also.
This means that only the root of a graph of objects actually needs to be passed to makePersistent(); all other objects in the graph implicitly become persistent also. This makes programming much easier.