Property Sets

Lets assume we have a Java class which holds some parameters we want to be able to edit later, e.g. in a GUI for some image analysis tool:

public static class ClusterAlgoParams {
    int clusterCount;
    double threshold;
    // ...
}

This class shall serve as the data model in the MVC architecture of our GUI. Since our model is a POJO, it does not automatically have the ability to inform the controller (= the binding) if values change. The Ceres binding framework allows to "wrap" instances of such plain Java classes using the PropertySet interface. A property set is basically a bucket of (name:String/value:Object) pairs associated with some meta data (represented by the PropertyDescriptor class). A property set also fires change events, if a property value changes. The PropertyContainer class is the default implementation of the PropertySet interface and provides some usefull factory methods that wrap {{Map<String,Object>}}s and plain {{Object}}s.

ClusterAlgoParams params = new ClusterAlgoParams();
// ...
PropertySet ps = PropertyContainer.createObjectBacked(params);

Now that the ClusterAlgoParams are wrapped by the property set, we can add meta data to each value in order to specify the units, a description, a Validator, a Converter or properties used to configure the bound GUI components:

ClusterAlgoParams params = new ClusterAlgoParams();
// ...
PropertyDescriptor pd = ps.getPropertyDescriptor("clusterCount");
pd.setDisplayName("Number of clusters");
pd.setValueRange(new ValueRange(2, 256));
// ...

Swing Binding

Once we have the configured property set (the model), we can create the bindings (the controllers) for the Java Swing GUI components (the views):

JTextField textField;
JSpinner spinner;
// ...
BindingContext ctx = new BindingContext(ps);
ctx.bind("clusterCount", textField);
ctx.bind("threshold", spinner);

Properties

The values in the property set are represented by the Property class. In the example above, all properties in the set are linked to the fields of the wrapped objects. Additionally, properties can also be linked to entries in a Map<String, Object>:

PropertySet ps;
Map<String, Object> map;
// ...
ps.addProperty(Property.create(map, "auxDataFile", File.class)); // property linked to entry in the map
ps.addProperty(Property.create("debug", Boolean.TYPE));          // property that provides its own value
//...

If neither a plain Java object nor a Map<String,Object> fits your needs, you can implement your own PropertyAccessor and create a custom value model by using the ValueModel constructor directly:

PropertySet ps;
Map<String, Object> map;
PropertyDescriptor pd = new PropertyDescriptor();
PropertyAccessor pa = new MyPropertyAccessor(/*...*/);
// ...
ps.addProperty(new Property(pd, pa));
//...