Tiny JDO tutorial

1. Where to find Speedo ?
2. The Speedo distribution
3. Running the Invoice example
4. Tiny JDO tutorial
5. Use of objects persistent with JDO
6. To fetch a PersistenceManager instance
7. To fetch a PersistenceManagerFactory instance
8. To make persistent an object
9. To delete a persistent object
10. To fetch a persistent object by its identifier
11. To fetch a persistent an object with criterias (Query)
12. To fetch all persistent instance of a class (Extent)

Use of objects persistent with JDO

The persistent 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 transient (PersistenceManager.makeTransient(Object)) the instance.

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: Don't forget to close the PersistenceManager when you finish to use it.

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.properties"));
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory(p);

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

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

To make persistent an object

To make persistent an object 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 writing on the data support is done when the PersistenceManager instance is closed.

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 removing instance on the data support is done when the PersistenceManager instance is closed.

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 field of the class. Both case are shown with an example

• Example with a basic identifier (field: int number):
  

  PersistenceManager pm = pmf.getPersistenceManager();
  Object oid = pm.objectIdInstance(Invoice.class, new Integer(54321));
  Invoice i = (Invoice) pm.getObjectById(oid, false);
  ... //use of the 'i' variable
  pm.close();

  Note that the integer value must be convert to the corresponding object value (java.lang.Integer).
  

• Example with a composite identifier:
  

  PersistenceManager pm = pmf.getPersistenceManager();
  Object oid = pm.objectIdInstance(Address.class, new AddressID("Seb", "myStreet", "myTown"));
  Address a = (Address) pm.getObjectById(oid, false);
  ... //use of the 'a' variable
  pm.close();

To fetch a persistent an object with criterias (Query)

To make a query you need a PersistenceManage instance in order to fetch Query object. The following example searches the addresses 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();

Then a filter is defined as an equality between the field 'name' and the parameter 'myParam'. Note that the filter is a parenthesed expresion (It is required by the 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 (the iterators included).

To fetch all persistent instance of a class (Extent)

To obtain an extent 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 the inheritance and then only the 'false' are supported.

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