JavaFX Programmatic POJO Expression Bindings (Part III)

Update: If you need help, have comments or want to contribute to the ongoing effort please visit the JFXtras GitHub site and file an issue

Collection/Map Binding

In Part I and Part II of the JavaFX POJO bindings I introduced possible mechanisms for binding JavaFX control properties to POJOs without having to create all the boilerplate code for the fields of your POJOs. It offered a way to bind POJO fields to JavaFX controls, but excluded POJO fields that contain collections or maps. Since then I have refined the adapter to include bindings that support bindings to/from POJO fields that are of type List, Set, and Map to/from ObservableList, ObservableSet, and ObservableMap. That means you can now bind your POJO fields that carry one of these collection/map types to a ListView, TableView, etc. items and/or their corresponding selections. The source code for the BeanPathAdapter can be downloaded from the JFXtras.org website (or you can view the latest source: BeanPathAdapter/BeanPathAdapterTestApp).

Usage

One of the features of the BeanPathAdapter is that we can bind different JavaFX collection/map types (ObservableList/ObservableSet/ObservableMap) with a different POJO field collection/map types (List/Set/Map). To demo this we’ll stick with the same “Person” example that we used in Part I/II, but this time we’ll add a few fields to demonstrate collection binding. Our POJO will contain Sets that we will use to bind to/from a ListView‘s items (ObservableList) and it’s selectionModel (MultipleSelectionModel). We’ll use the allLanguages/allHobbies fields as the item values for a ListView and the languages/hobbies fields as the selection values of the ListView:

public static class Person {
	...
	private Set languages;
	private Set hobbies;
	private Set allLanguages;
	private Set allHobbies;
	...
	public Set getLanguages() {
		return languages;
	}
	public void setLanguages(Set languages) {
		this.languages = languages;
	}
	public Set getHobbies() {
		return hobbies;
	}
	public void setHobbies(Set hobbies) {
		this.hobbies = hobbies;
	}
	public Set getAllLanguages() {
		return allLanguages;
	}
	public void setAllLanguages(Set allLanguages) {
		this.allLanguages = allLanguages;
	}
	public Set getAllHobbies() {
		return allHobbies;
	}
	public void setAllHobbies(Set allHobbies) {
		this.allHobbies = allHobbies;
	}
}
public static class Hobby {
	private String name;
	private String description;

	public String getName() {
		return name;
	}
	public void setName(String name) {
		this.name = name;
	}
	public String getDescription() {
		return description;
	}
	public void setDescription(String description) {
		this.description = description;
	}
}

The languages will contain simple String values and the hobbies will use a more complex Hobby POJO where we will supply a path to Hobby#name that the adapter will use as the display value of each item in the example ListView. As far as the JavaFX control is concerned it will always contain values of the same (or a coercible counterpart) type as the Hobby#name field.

Person person = new Person();
BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);

// initial items will never be seen because the
// POJO bean allHobbies will take presidence
ListView llv = new ListView<>(
		FXCollections.observableArrayList(new String[]{
		"Language Item Never Shown"}));
// bind the items to/from Person#allLanguages
personPA.bindContentBidirectional("allLanguages", null, String.class,
		llv.getItems(), String.class, null);
// we need to pass in the SelectionModel of
// llv.getSelectionModel() so that updates to the
// ReadOnlyUnbackedObservableList can be updated
personPA.bindContentBidirectional("languages", null,
		String.class, llv.getSelectionModel().getSelectedItems(),
		String.class,
		llv.getSelectionModel());

// initial items will never be seen because the
// POJO bean allHobbies will take presidence
ListView hlv = new ListView<>(
		FXCollections.observableArrayList(new String[]{
		"Hobby Item Never Shown"}));
// bind the items to/from Person#allHobbies
personPA.bindContentBidirectional("allHobbies", "name", Hobby.class,
		hlv.getItems(), String.class, null);
// we need to pass in the SelectionModel of
// hlv.getSelectionModel() so that updates to the
// ReadOnlyUnbackedObservableList can be updated
personPA.bindContentBidirectional("hobbies", "name",
		Hobby.class, hlv.getSelectionModel().getSelectedItems(),
		String.class,
		hlv.getSelectionModel());

Now that the items in the ListView are bound to/from the Person#allLanguages/Person#allHobbies fields and the selections for those items are bound to the Person#languages/Person#hobbies fields changes in the controls will be reflected in the corresponding POJO fields. Due to the nature of POJO field change capture (as well as the collection/map) you may need to call personPA.setBean(person); after changes are made DIRECTLY to POJO collections/maps to see them within the JavaFX controls they are bound to. One of the nice things about the decoupled nature of collection/map bindings is that the JavaFX control will always have a primitive value (or a primitive boxed type). This allows you to add/put/remove a primitive value to/from the control while the adapter handles any instantiation/conversion needed to get the primitive value reflected in your POJO’s collection/map. For example, the sample application has a “Add Hobby” button. When clicked it takes the String value of the hobby name entered and calls listView.getItems().add(textField.getText());. The adapter handles the instantiation of a new Hobby, calls newHobby.setName(nameFromTextField), and ultimately calls person.getAllHobbies().add(newHobby). None of which requires any additional steps by the implementer.

Summary of Usage

Here are a few usage examples:

1. Binding bean fields to multiple JavaFX control properties of different types:

   // Assuming "age" is a double field in person we can bind it to a 
   // Slider#valueProperty() of type double, but we can also bind it
   // to a TextField#valueProperty() of type String. 
   Person person = new Person();
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   Slider sl = new Slider();
   TextField tf = new TextField();
   personPA.bindBidirectional("age", sl.valueProperty());
   personPA.bindBidirectional("age", tf.valueProperty());
   

2. Binding beans within beans:

   // Binding a bean (Person) field called "address" that contains another 
   // bean (Address) that also contains a field called "location" with a 
   // bean (Location) field of "state" (the chain can be virtually endless
   // with all beans being instantiated along the way when null).
   Person person = new Person();
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   TextField tf = new TextField();
   personPA.bindBidirectional("address.location.state", tf.valueProperty());
   

3. Binding non-primitive bean paths to JavaFX control properties of the same non-primitive type:

   // Assuming "role" is a "Role" field in a "Person" class we can 
   // bind it to a ComboBox#valueProperty() of the same type. The "Role" 
   // class should override the "toString()" method in order to show a 
   // meaningful selection value in the example ComboBox.
    Role r1 = new Role();
    Role r2 = new Role();
    r1.setName("Administrator");
    r2.setName("User");
    ComboBox<Role> cb = new ComboBox<>();
    cb.getItems().addAll(r1, r2);
    Person person = new Person();
    BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
    personPA.bindBidirectional("role", cb.valueProperty(), Role.class);
   

4. Binding collections/maps fields to/from observable collections/maps (i.e. items in a JavaFX control):

   // Assuming "allLanguages" is a collection/map field in person we can
   // bind it to a JavaFX observable collection/map
   Person person = new Person();
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   ListView<String> lv = new ListView<>();
   personPA.bindContentBidirectional("allLanguages", null, String.class, lv.getItems(), String.class, null, null);
   

5. Binding collections/maps fields to/from observable collections/maps selections (i.e. selections in a JavaFX control):

   // Assuming "languages" is a collection/map field in person we can
   // bind it to a JavaFX observable collection/map selections
   Person person = new Person();
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   ListView<String> lv = new ListView<>();
   personPA.bindContentBidirectional("languages", null, String.class, lv.getSelectionModel().getSelectedItems(), String.class, lv.getSelectionModel(), null);
   

6. Binding collection/map fields to/from observable collections/maps selections using an items from another observable collection/map as a reference (i.e. selections in a JavaFX control that contain the same instances as what are in the items being selected from):

   // Assuming "languages" and "allLanguages" are a collection/map 
   // fields in person we can bind "languages" to selections made from
   // the items in "allLanguages" to a JavaFX observable collection/map 
   // selection
   Person person = new Person();
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   ListView<String> lv = new ListView<>();
   personPA.bindContentBidirectional("languages", null, String.class, lv.getSelectionModel().getSelectedItems(), String.class, lv.getSelectionModel(), "allLanguages");
   

7. Binding complex bean collection/map fields to/from observable collections/maps selections and items (i.e. selections in a JavaFX control that contain the same bean instances as what are in the items being selected):

   // Assuming "hobbies" and "allHobbies" are a collection/map 
   // fields in person and each element within them contain an 
   // instance of Hobby that has it's own field called "name" 
   // we can bind "allHobbies" and "hobbies" to the Hobby "name"s 
   // for each Hobby in the items/selections (respectively) to/from
   // a ListView wich will only contain the String name of each Hobby
   // as it's items and selections
   Person person = new Person();
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   ListView<String> lv = new ListView<>();
   // bind items
   personPA.bindContentBidirectional("allHobbies", "name", Hobby.class, lv.getItems(), String.class, null, null);
   // bind selections that reference the same instances within the items
   personPA.bindContentBidirectional("hobbies", "name", Hobby.class, lv.getSelectionModel().getSelectedItems(), String.class, lv.getSelectionModel(), "allHobbies");
   

8. Binding bean collection/map fields to/from multiple JavaFX control observable collections/maps of the same type (via bean collection/map):

   Person person = new Person();
   Hobby hobby1 = new Hobby();
   hobby1.setName("Hobby 1");
   Hobby hobby2 = new Hobby();
   hobby2.setName("Hobby 2");
   person.setAllHobbies(new LinkedHashSet<Hobby>());
   person.getAllHobbies().add(hobby1);
   person.getAllHobbies().add(hobby2);
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   ListView<String> lv = new ListView<>();
   personPA.bindContentBidirectional("allHobbies", "name", Hobby.class, 
   		lv.getItems(), String.class, null, null);
   ListView<String> lv2 = new ListView<>();
   personPA.bindContentBidirectional("allHobbies", "name", Hobby.class, 
   		lv2.getItems(), String.class, null, null);
   

9. Binding bean collection/map fields to/from multiple JavaFX control observable collections/maps of the same type (via JavaFX control observable collection/map):

   // When the bean collection/map field is empty/null and it is
   // bound to a non-empty observable collection/map, the values
   // of the observable are used to instantiate each item bean
   // and set the item value (Hobby#setName in this case)
   Person person = new Person();
   final ObservableList<String> oc = FXCollections.observableArrayList("Hobby 1", "Hobby 2", "Hobby 3");
   BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
   ListView<String> lv = new ListView<>(oc);
   personPA.bindContentBidirectional("allHobbies", "name", Hobby.class, 
   		lv.getItems(), String.class, null, null);
   ListView<String> lv2 = new ListView<>(); // <-- notice that oc is not passed
   personPA.bindContentBidirectional("allHobbies", "name", Hobby.class, 
   		lv2.getItems(), String.class, null, null);
   

10. Switching beans:

    // Assuming "age" is a double field in person...
    final Person person1 = new Person();
    person1.setAge(1D);
    final Person person2 = new Person();
    person2.setAge(2D);
    final BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person1);
    TextField tf = new TextField();
    personPA.bindBidirectional("age", tf.valueProperty());
    Button btn = new Button("Toggle People");
    btn.setOnMouseClicked(new EventHandler<MouseEvent>() {
    	@Override
    	public void handle(MouseEvent event) {
    		// all bindings will show relevant person data and changes made
    		// to the bound controls will be reflected in the bean that is 
    		// set at the time of the change
    		personPA.setBean(personPA.getBean() == person1 ? person2 : person1);
    	}
    });
    

11. Date/Calendar binding:

    // Assuming "dob" is a java.util.Date or java.util.Calendar field 
    // in person it can be bound to a java.util.Date or 
    // java.util.Calendar JavaFX control property. Example uses a
    // jfxtras.labs.scene.control.CalendarPicker
    final Person person = new Person();
    final BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
    CalendarPicker calendarPicker = new CalendarPicker();
    personPA.bindBidirectional("dob", calendarPicker.calendarProperty(), Calendar.class);
    

12. TableView items binding:

    // Assuming "name"/"description" are java.lang.String fields 
    // in Hobby and "hobbies" is a List/Set/Map in Person
    final Person person = new Person();
    final BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
    TableView<Hobby> table = new TableView<>();
    TableColumn<Hobby, String> nameCol = new TableColumn<>("Hobby Name");
    nameCol.setMinWidth(100);
    nameCol.setCellValueFactory(
            new PropertyValueFactory<Hobby, String>("name"));
    TableColumn<Hobby, String> descCol = new TableColumn<>("Hobby Desc");
    descCol.setMinWidth(100);
    descCol.setCellValueFactory(
            new PropertyValueFactory<Hobby, String>("description"));
    table.getColumns().addAll(nameCol, descCol);
    personPA.bindContentBidirectional("hobbies", null, String.class,
    	table.getItems(), Hobby.class, null, null);
    

13. Listening for global changes:

    final Person person = new Person();
    final BeanPathAdapter<Person> personPA = new BeanPathAdapter<>(person);
    // use the following to eliminate unwanted notifications
    // personPA.removeFieldPathValueTypes(FieldPathValueType.BEAN_CHANGE, ...)
    personPA.fieldPathValueProperty().addListener(
     	new ChangeListener<FieldPathValue>() {
     	@Override
     	public void changed(
     		final ObservableValue<? extends FieldPathValue> observable,
     		final FieldPathValue oldValue, final FieldPathValue newValue) {
     			System.out.println("Value changed from: " + oldValue
     				+ " to: " + newValue);
     		}
     	});
    

In Action

Here is some screen shots of the demo application in action (can be downloaded from the JFXtras.org website or view the latest snapshot from: BeanPathAdapter/BeanPathAdapterTestApp):