As you read in the guide for PersistenceManagerFactory, to control the persistence of your objects you will require at least one PersistenceManagerFactory. Once you have obtained this object you then use this to obtain a PersistenceManager (PM). A PersistenceManager provides access to the operations for persistence of your objects. This short guide will demonstrate some of the more common operations. For example with a web application you would have one PMF representing the datastore, present for the duration of the application, and then have a PM per request that comes in, closing it before responding.
|Important : A PersistenceManagerFactory is designed to be thread-safe. A PersistenceManager is not. Note that if you set the persistence property javax.jdo.option.Multithreaded this acts as a hint to the PMF to provide PersistenceManagers that are usable with multiple threads. While DataNucleus makes efforts to make this PersistenceManager usable with multiple threads, it is not guaranteed to work multi-threaded in all situations, particularly around second class collection/map fields.|
PersistenceManager pm = pmf.getPersistenceManager();
You then perform all operations that you need using this PersistenceManager and finally you must close it. Forgetting to close it will lead to memory/resource leaks.
You likely will be performing all operations on a PersistenceManager within a transaction, whether your transactions are controlled by your JavaEE container, by a framework such as Spring, or by locally defined transactions. Alternatively you can perform your operations non-transactional. In the examples below we will omit the transaction demarcation for clarity.
The main thing that you will want to do with the data layer of a JDO-enabled application is persist your objects into the datastore. As we mentioned earlier, a PersistenceManagerFactory represents the datastore where the objects will be persisted. So you create a normal Java object in your application, and you then persist this as follows
This will result in the object being persisted into the datastore, though clearly it will not be persistent until you commit the transaction. The LifecycleState of the object changes from Transient to PersistentClean (after makePersistent), to Hollow (at commit).
Once you have persisted an object, it has an "identity". This is a unique way of identifying it. You can obtain the identity by calling
Object id = pm.getObjectId(obj);
Alternatively by calling
Object id = pm.newObjectIdInstance(cls, key);
So what ? Well the identity can be used to retrieve the object again at some other part in your application. So you pass the identity into your application, and the user clicks on some button on a web page and that button corresponds to a particular object identity. You can then go back to your data layer and retrieve the object as follows
Object obj = pm.getObjectById(id);
A DataNucleus extension is to pass in a String form of the identity to the above method. It accepts identity strings of the form
where the key is the identity value (datastore-identity) or the result of PK.toString() (application-identity). So for example we could input
obj = pm.getObjectById("mydomain.MyClass:3");
There is, of course, a bulk load variant too
Object objs = pm.getObjectsById(ids);
When you call the method getObjectById if an object with that identity is found in the cache then a call is, by default, made to validate it still exists. You can avoid this call to the datastore by setting the persistence property datanucleus.findObject.validateWhenCached to false.
An alternate form of the getObjectById method is taking in the class of the object, and the "identity". This is for use where you have a single field that is primary key. Like this
Object id = pm.getObjectId(MyClass.class, 123);
where 123 is the value of the primary key field (numeric). Note that the first argument could be a base class and the real object could be an instance of a subclass of that.
When you need to delete an object that you had previous persisted, deleting it is simple. Firstly you need to get the object itself, and then delete it as follows
Object obj = pm.getObjectById(id); // Retrieves the object to delete pm.deletePersistent(obj);
To modify a previously persisted object you need to retrieve it (getObjectById, query, getExtent) and then modify it and its changes will be propagated to the datastore at commit of the transaction.
Don't forget that you can also use bulk update to update a group of objects of a type.
You often have a previously persisted object and you want to use it away from the data-access layer of your application. In this case you want to detach the object (and its related objects) so that they can be passed across to the part of the application that requires it. To do this you do
Object detachedObj = pm.detachCopy(obj); // Returns a copy of the persisted object, in detached state
The detached object is like the original object except that it has no StateManager connected, and it stores its JDO identity and version. It retains a list of all fields that are modified while it is detached. This means that when you want to "attach" it to the data-access layer it knows what to update.
As an alternative, to make the detachment process transparent, you can set the PMF property datanucleus.DetachAllOnCommit to true and when you commit your transaction all objects enlisted in the transaction will be detached.
You've detached an object (shown above), and have modified it in your application, and you now want to attach it back to the persistence layer. You do this as follows
Object attachedObj = pm.makePersistent(obj); // Returns a copy of the detached object, in attached state
In the situation where you have an object and you think that its values may have changed in the datastore you can update its values to the latest using the following
What this will do is as follows
If the object had any changes they will be thrown away by this step, and replaced by the latest datastore values.
Each PersistenceManager maintains a cache of the objects that it has encountered (or have been "enlisted") during its lifetime. This is termed the Level 1 Cache. It is enabled by default and you should only ever disable it if you really know what you are doing. There are inbuilt types for the Level 1 (L1) Cache available for selection. DataNucleus supports the following types of L1 Cache :-
You can specify the type of L1 cache by providing the persistence property datanucleus.cache.level1.type. You set this to the value of the type required. If you want to remove objects from the L1 cache programmatically you should use the pm.evict or pm.evictAll methods.
Objects are placed in the L1 cache (and updated there) during the course of the transaction. This provides rapid access to the objects in use in the users application and is used to guarantee that there is only one object with a particular identity at any one time for that PersistenceManager. When the PersistenceManager is closed the L1 cache is cleared.
If you are using a PersistenceManager in a multitenancy environment, and want to have a PersistenceManager per tenant you would set the "Tenant ID" on the PersistenceManager after creation.
Subsequently on database accesses for classes that are using multitenancy you will likely see use of the "Tenant ID" discriminator column.