Tiny JDO tutorial

  1. Use of objects made persistent with JDO
  2. How to fetch a PersistenceManager instance
  3. How to fetch a PersistenceManagerFactory instance
  4. How to make an object persistent
  5. How to delete a persistent object
  6. How to fetch a persistent object by its identifier
  7. How to fetch a persistent an object with criterias (Query)
  8. How to fetch all persistent instances of a class (Extent)

Back to the Speedo documentation


Use of objects made persistent with JDO

Persistent objects must be enhanced by a JDO implementation. In case of Speedo you must use the Speedo ant task to do it. This step should be done just after the compilation of your classes.

When a persistent instance is used, a PersistenceManager must be opened otherwise you must make the instance transient (PersistenceManager.makeTransient(Object)).

How to fetch a PersistenceManager instance

To fetch a PersistenceManager instance you need a PersistenceManagerFactory instance (see the next section to learn how to fetch a PersistenceManagerFactory instance).

PersistenceManagerFactory pmf = ...;
PersistenceManager pm = pmf.getPersistenceManager();
...
p.close();

IMPORTANT: Do not forget to close the PersistenceManager when you have finished using it.

How to fetch a PersistenceManagerFactory instance

To fetch a PersistenceManagerFactory instance you must use the JDOHelper class with a properties instance. The properties permit to configure and to choose the right instance.

Properties p = new Properties();
p.load(new FileInputStream("speedo-jdo.properties"));
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(p);

You should keep the PersistenceManagerFactory instance as a global variable in your persistent application.

In an application server, the PersistenceManagerFactory is often available as a resource, like a SQL datasource, through JNDI. Indeed the JDO implementation is often integrated as a resouce adapter (JCA).

How to make an object persistent

To make an object persistent you must call the makePersistent method on a PersistenceManager instance.

PersistenceManager pm = pmf.getPersistenceManager();
Address addr = new Address("Seb", "myStreet", "myZip", "myTown", "France");
...
pm.makePersistent(addr);
...
pm.close();

If you do not use a transaction, the write operation on the data support is done when the PersistenceManager instance is closed.

How to delete a persistent object

To delete a persistent object you must call the deletePersistent method on a PersistenceManager instance.

PersistenceManager pm = pmf.getPersistenceManager();
Address addr = ...;
pm.deletePersistent(addr);
...
pm.close();

If you do not use a transaction, the removal of the instance on the data support is done when the PersistenceManager instance is closed.

How to fetch a persistent object by its identifier

A persistent object has an identifier. It can be one the primitive field of the class or a group of several primitive fields of the class. Both cases are shown with an example



How to fetch a persistent an object with criterias (Query)

To ask a query, you need a PersistenceManage instance in order to fetch Query objects. The following example searches the addresses for which the name is equal to the value "Seb".

PersistenceManager pm = pmf.getPersistenceManager();
Query query = pm.getQuery(Address.class);
query.setFilter("(name == myParam)");
query.declareParameters("String myParam");
Collection col = (Collection) query.execute("Seb");
Iterator it = col.iterator();
if (it.hasNext()) {
//there is a result
while(it.hasNext()) {
Address a = (Address) it.next();
...
}
} else {
//no persistent object found
...
}
query.closeAll();
...
pm.close();

A filter is defined as an equality between the field 'name' and the parameter 'myParam'. Note that the filter is a parenthesed expresion (required by the JDO specification). The result of the evaluation is a java.util.Collection on which you can obtain an iterator over the elements found.

IMPORTANT: you should close the query by calling the 'closeAll()' method when you have finished to use the result of the evalution (including the iterators).

How to fetch all persistent instance of a class (Extent)

To obtain an Extent (containing all instances of a persistent class), you need a PersistenceManage instance. With the Extent you can get an iterator over all instances.

PersistenceManager pm = pmf.getPersistenceManager();
Extent extent = pm.getExtent(Address.class, false);
Iterator it = extent.iterator();
while(it.hasNext()) {
Address a = (Address) it.next();
...
}
extent.closeAll();
...
pm.close();

The boolean parameter of the 'getExtent' method indicates if the sub-classes are expected or not. Currently Speedo does not support inheritance and thus only 'false' is supported.

IMPORTANT: you should close the extent by calling the 'closeAll()' method when you have finished to use the result of the evalution (including the iterators).