Package org.joda.property

Joda property based domain model

See:
Description

Interface Summary

Bean	Bean is the interface used to mark a class as a JavaBean.
Bean.Internal	Interface used during the cloning process.
BeanList	BeanList defines interfaces which want to specify a typecast list Bean objects.
ModelAttribute	ModelAttribute represents an attribute held on a ModelElement.
ModelElement	ModelElement defines the abstract concept of part of the Joda bean/property model structure.
Property	Property defines the concept of a property on a Bean.
Property.Internal	Interface used during the cloning process.

Class Summary

JodaFactory	Factory used to create new PropertyTools.
JodaUtils	JodaUtils groups together useful routines for handling Joda object models
ListPropertyChangeEvent	ListPropertyChangeEvent is the event object sent when a list property changes.
ListPropertyChangeEvent.Change
PropertyValueChangeEvent	PropertyValueChangeEvent is the event object sent when the value of a property is changed.

Exception Summary

FactoryJodaException	Exception thrown when a factory cannot create an object because it does not handle the specified hint.
NullValueJodaException	Exception thrown when an attempt is made to query or modify a property which is currently null.
UnmodifiableJodaException	Exception thrown when an attempt is made to modify a property which is unmodifiable.

Package org.joda.property Description

Joda property based domain model

The JavaBean model was originally designed as a component model. The primary consideration was GUI drag and drop editors. Large scale enterprise domain models were not the motivation. Despite this, the same basic structure has been used. The Joda property based domain model aims to re-focus the basic design of JavaBeans. In doing this it should be realised that not everything that can be achieved with JavaBeans can be achieved with Joda. This is not necessarily a bad thing, as typically what can't be achieved should not be on a domain model anyway.

This package defines the interfaces used when working with a Joda domain model. The basic concepts are familiar - Bean and Property. However the Joda model introduces an optional new syntax to beans. In addition to getFoo() and setFoo() you can define foo(). This third method gives access to a Property object which has certain features:

• Set from an Object without reflection - Useful for framework code like XML parsers
• Get as an Object without reflection - Useful for framework code like XML outputters
• Event listening - an event listener can be added to a Property to listen to changes in the value, useful for GUI bindings for example
• Dynamic modifiability - a Property can be set to be unmodifiable or read only on the fly, simulating the const keyword in C
• Attributes - a Map of freeform String attributes that enable extra data to be attached to a property in the bean. One example of this in use is to attach an error code to the property that caused the error.

  Defining the model - the Architectural decision

  A Joda model can be defined in two main ways, either as interfaces or classes. The interface approach is quicker to code for simple models that involve no code in the get or set methods and no business logic on the model. It also requires the use of a Factory to create the objects. This approach is useful for temporary data holders. The class approach involves more work initially but gives greater control overall.

  Interface approach

  The model is defined as interfaces. The classes are generated at runtime by the Java 1.3 Proxy class. The interfaces must extend the Bean interface and be instantiated by the JodaFactory class. The property style method must be specified in this approach. The get/set methods are optional and if they do exist must follow a strict naming convention.

  public interface Person extends Bean {
    // required
    StringProperty surname();
    // optional
    String getSurname();
    // optional
    setSurname(String surname);
    // recommended factory technique (inner class in interface!)
    public class Factory {
      public static Person create() {
        return (Person) JodaFactory.create(Person.class);
      }
    }
  }
  // Factory usage
  Person p = Person.Factory.create();

  Class approach

  More complex data models need to be coded as classes. This permits functional methods to be coded as normal on the model. It also permits validation of the data in set methods provided that only runtime exceptions/asserts are thrown. If this approach is used, the classes must implement the Bean interface. This is best achieved by extended the AbstractBean class. The class must have a no arguments constructor, but it may does not have to be declared public (a non-public constructor can be called by reflection if the SecurityPermission allows). Two variations of the class approach exist and may be used interchangably on the same bean.

  The standard approach delegates all control of the property to the Property object. No attribute is created on the bean and the methods all follow the same pattern. Validation is not supported in this approach however.

  public class Person extends AbstractBean {
    // required no-args constructor but may be non-public if desired
    public Person() {
    }
    // required
    public StringProperty surname() {
      return (StringProperty) getProperty("surname");
    }
    // optional
    public String getSurname() {
      return surname().get();
    }
    // optional
    public void setSurname(String surname) {
      surname().set(surname);
    }
    // initialisation not required as it can be inferred by reflection
    // (if mixed with the wrapper approach then initialisation is required)
  }

  The wrapper approach creates a Property object that calls back to the bean's get and set methods to store the data. As these are normal get and set methods, they can support validation checking, although they can only throw RuntimeExceptions. Note that you cannot access the property method from within get or set method as that could cause recursive behaviour. As can be seen, there is quite an overhead in writing a set method - that is what Joda tries to hide from you.

  public class Person extends AbstractBean {
    private String iSurname = null;
    // required no-args constructor but may be non-public if desired
    public Person() {
    }
    // optional (but usually present)
    public StringProperty surname() {
      return (StringProperty) getProperty("surname");
    }
    // required
    public String getSurname() {
      return iSurname;
    }
    // required, but may be non-public
    public void setSurname(String surname) {
      checkModifiable(surname());
      Object oldValue = iSurname;
      iSurname = surname
      surname().firePropertyValueChanged(oldValue, iSurname);
    }
    // initialisation is required
    protected initPropertyMap() {
      addPropertyWrapper("surname");
    }
  }