ObjectGraphBuilder is a builder for an arbitrary graph of beans that follow the JavaBean convention, its useful for creating test data for example.

Let's say that the following classes belong into your domain model:

package com.acme

class Company {
   String name
   Address address
   List employees = []
}

class Address {
   String line1
   String line2
   int zip
   String state
}

class Employee {
   String name
   int employeeId
   Address address
   Company company
}

With ObjectGraphBuilder building a Company with three employees is as easy as

def builder = new ObjectGraphBuilder()
// uncomment the following line if running this script with GroovyConsole
//builder.classloader = getClass().classLoader
builder.classNameResolver = "com.acme"

def acme = builder.company( name: 'ACME' ){
   3.times {
      employee( id: it.toString(), name: 'Drone ${it}' )
   }
}

assert acme != null
assert acme.employees.size() == 3

Here is what's happening behind the scenes:

1. the builder will try to match a node name into a Class, using a default ClassNameResolver strategy that requires a package name.
2. then an instance of said class must be created, using a default NewInstanceResolver strategy that calls a no-args constructor.
3. the parent/child relationship must be resolved for nested nodes, here it gets a little tricky as two other strategies come into play. RelationNameResolver will yield the name of the child property in the parent, and the name of the parent property in the child (if any, in this case, Employee has a parent property aptly named 'company'). ChildPropertySetter will 'insert' the child into the parent taking into account if the child belongs to a Collection or not (in this case employees should be a list of Employee instances in Company).

All 4 strategies have a default implementation that work as expected if the code follows the usual conventions for writing JavaBeans. But if by any chance any of your beans does not follow the convention you may plug your own implementation of each strategy. Each strategy setter is Closure friendly, for example

builder.newInstanceResolver = { klass, attributes ->
   if( attributes.foo ){
      return klass.newInstance( [attributes.foo] as Object[] )
   }
   // default no-args constructor
   klass.newInstance()
}

ObjectGraphBuilder supports ids per node as SwingBuilder does, meaning that you can 'store' a reference to a node in the builder, this is useful to relate one instance with many others as well. Because a property named 'id' may be of business meaning in some domain models ObjectGraphBuilder has a strategy named IdentifierResolver that you may configure to change the default name value ('id'). The same may happen with the property used for referencing a previously saved instance, a strategy named ReferenceResolver will yield the appropriate value (default is 'refId'):

def company = builder.company( name: 'ACME' ) {
   address( id: 'a1', line1: '123 Groovy Rd', zip: 12345, state: 'JV' )
   employee(  name: 'Duke', employeeId: 1, address: a1 )
}

def company = builder.company( name: 'ACME' ) {
   address( id: 'a1', line1: '123 Groovy Rd', zip: 12345, state: 'JV' )
   employee(  name: 'Duke', employeeId: 1 ){
      address( refId: 'a1' )
   }
}

Its worth mentioning that you cannot modify the properties of a referenced bean.

For those rare occasions where ObjectGraphBuilder can't locate your classes (it happens when you run a script using groovyConsole) you may define a classLoader for ObjectGraphBuilder to resolve classes. Try for example running the following script inside groovyConsole and then comment out the classLoader property.

class Conference {
   String name
   List speakers = []
}

class Speaker {
   String name
}

def ogb = new ObjectGraphBuilder( classLoader: getClass().classLoader )
def j1 = ogb.conference( name: 'JavaOne') {
   speaker( name: 'Duke' )
}
assert j1.speakers.size() == 1
assert j1.speakers[0].name == 'Duke'