# org.melati.poem ODMG User Guide (document $Revision: 1.2 $)

## Introduction

### POEM and ODMG

This guide describes the ODMG API for Melati POEM (Persistent Object Engine for Melati): the layer which provides an ODMG type view onto a JDBC compliant database. It assumes you know how to setup and use POEM generally - so see that documentation first.

### Other information

See also the Melati POEM User Guide
See also the ODMG site

### Anatomy of an ODMG session

The test program OdmgTest.java provides a simple example of using the ODMG api to create, query and amend objects.

First thing you do is create an open database connection.

>         Database db = org.melati.poem.odmg.ODMGFactory.getNewDatabase();
>         db.open("odmgplaying",Database.OPEN_READ_WRITE);

The "odmgplaying" is the name of the POEM Logical Database, as defined in your `org.melati.LogicalDatabase.properties` file. See the Melati POEM API documentation for more information on this.

You then need to create and open a transaction in which to do any query or update work. Note that transactions are thread based - thus all work in the same thread is assumed to be in the same transaction. Also the current wrapper does not support multi-threaded processing, that is, you cannot open a transaction in one thread and then access it in another.

>         Transaction tx = org.melati.poem.odmg.ODMGFactory.getNewTransaction(db);
>         tx.begin();

You can now access and update the database.

>         DCollection parents = (DCollection) db.lookup("parent");

>         //clear out old crap
>         parents.removeAll(parents);

>         System.out.println("ADDING PARENTS");
>         for (int i=0; i<10; i++)
>         {
>           Parent p = newParent();
>           p.setName("parent-"+parents.size());
>           parents.add(p);
>         }

>         System.out.println("PARENTS DESCENDING");
>         Iterator iter = parents.select("order by name desc");
>         while (iter.hasNext())
>         {
>           Parent p = (Parent)iter.next();
>           System.out.println("Parent:"+p.getName());
>         }

To then commit any changes you have made you need to then commit the transaction.

>         tx.commit();

## About this document

### Readership and purpose

- Users (programmers) should understand how to use POEM's API and how it fits in to its broader contex.

This document is intended to give details of how to use the ODMG API.

### History

The important points in the life of this document are listed below.

The CVS log for this document is:
$Log: ODMGPoemUserGuide.html,v $
Revision 1.2 2006/12/13 11:58:21 timp
New javadoc and db mount points
Revision 1.1 2005/11/21 22:01:49 timp
Moved from site/doc
Revision 1.2 2003/07/11 23:47:41 timp
remove a few broken links
Revision 1.1 2000/09/11 10:56:42 kimptoc
added some ODMG/POEM documentation