The purpose of these diagrams is to help grasp what's going on when issuing a db.commit() on objects with relationships. The following examples all use the same objects, Book and Author, but with different relationships between them.

(Note: the diagrams, along with complete test code, can also be found at http://jira.codehaus.org/browse/CASTOR-2854)

No relationship (Author)

changing a field of Author

db.begin();
Author a = db.load(Author.class, 1);
a.setName("Oolon Colluphid");
db.commit();

One-to-one relationship (Author <-- Book)

changing a field of Author

db.begin();
Book b = db.load(Book.class, 1);
Author a = b.getAuthor();
a.setName("Oolon Colluphid");
db.commit();

setting a new Author

db.begin();
Book b = db.load(Book.class, 1);
Author a = new Author();
a.setName("Oolon Colluphid");
b.setAuthor(a);
db.commit();

One-to-many relationship (Author --> Book)

add a new Book

db.begin();
Author a = db.load(Author.class, 1);
Collections bs = a.getBooks();
Book b = new Book();
b.setName("Some More Of God's Greates Mistakes");
bs.add(b);
db.commit();