Getting started

The Joda beans API is virtually totally defined as interfaces. All the main parts of the framework are interfaces, for example Property is the basic interface for all properties, whereas StringProperty extends that to represent a String.

Your domain model is also defined as interfaces. Classes to fulfill the interfaces are generated dynamically at runtime using the Java 1.3 Proxy class (or hopefully Apache BCEL in the future). For simple models, that is all that is required. More complex models will require a class to be written to specify those parts of the model which are non-standard. A factory is then used to create domain objects (as they are interfaces).

For example, consider a simple Person class:

public interface Person extends Bean {
  StringProperty surname();
  String getSurname();
  void setSurname(String surname);

  IntegerProperty age();
  int getAge();
  void setAge(int age);
}

This fully defines a simple Person class. To use this we might write:

  Person person = (Person) JodaFactory.create(Person.class);
  // we could write...
  String surname = person.surname().get();
  int surnameLength = person.surname().length();
  person.surname().set("Smith");
  // or alternatively we could write JavaBeans style...
  String surname = person.getSurname();
  int surnameLength = person.getSurname().length();
  person.setSurname("Smith");

This hasn't added a lot of benefit, but these features are much easier to write/use than using JavaBeans:

  Person person = (Person) JodaFactory.create(Person.class);
  // Get a property by name without reflection
  Property surnameProperty = person.getProperty("surname");
  // Query all the properties on a domain object without reflection
  Map allProperties = person.getPropertyMap();
  // XML
  String xml = new XMLOutputter().output(person);
  // Swing
  JTextField textField = new JTextField();
  new SwingBinder().bind(textField, person.surname());
  // XPath
  String surname = new XPath("/surname/text()").valueOf(person);
  // events
  PropertyChangeListener lnr = new MyListener();
  person.surname().addPropertyChangeListener(lnr);
  // dynamic modifiability
  person.surname().setModifiable(false);
  person.surname().setReadOnly();

Finally, lets consider a Profile class which contains a Person:

public interface Profile extends Bean {
  Person person();
  LinkProperty personLink();
  Person getPerson();
  void setPerson(Person person);
}

To use this we might write:

  Profile profile = (Profile) JodaFactory.create(Profile.class);
  // create a new Person (no factory !)
  Person person = profile.personLink().setNew();
  // get the surname
  String surname = profile.person().surname().get();
  // use XPath to get the surname property
  Property surnameProperty = (Property) new XPath(
      "/person/surname").selectSingleNode(profile);

This is really only a brief guide to what is possible. The basic classes have fairly self explanatory names (Property, StringProperty, BooleanProperty etc.) so building your first Joda domain model should be fairly easy. Then, if your needs require, the generic methods on Property can be used to query the model.