Introduction

There are three ways to create a Binding; the Fluent API, using the Bindings class builder methods and extending one of the abstract Binding classes to create a custom binding. We're going to look at this last method in this article.

You should understand how to create your own custom Binding class just so that you understand how Bindings work internally. This makes it much easier to understand how to use the builder method in the Bindings class - which you will probably use a lot.

How This Fits in the JavaFX Hierarchy

The Binding Interfaces

In JavaFX, Binding is an interface which extends Observable, and ObservableValue. These two super-interfaces are important because they supply the addListenter(), and removeListener() methods for both InvalidationListeners and ChangeListeners.

Bindings themselves rely on InvalidationListeners to control their updates. We'll see how this works. In fact, the two main methods that the Binding interface adds are the invalidate() and isValid methods. In practice, you'll rarely need to directly deal with either of those methods.

The Abstract Classes

In practice, virtually all custom Binding classes are created by extending one of the abstract Binding classes contained in the JavaFX library. These are all designed to handle bindings on different types of data. There is BooleanBinding, DoubleBinding, IntegerBinding, ListBinding, LongBinding, MapBinding, ObjectBinding, SetBinding, and StringBinding.

In general, all of these abstract classes are similar, differing only in the data types that they are concerned with. The Binding classes for collections have some additional methods that relate to aspects of collections, such as size or "empty". Also, all of these classes implement observable interfaces for their data types. So, an IntegerBinding implements ObservableIntegerValue.

Since they implement Binding, they will implement methods for addListener() (for both InvalidationListeners, and ChangeListeners). The bind() method for all of these classes is protected, so you cannot call it from your layout code - meaning that your bound dependencies need to be defined at the time that you instantiate the Binding.

The computeValue() Method

The vast majority of the time, all of the code that you write for a custom Binding class will be it's constructor and the computeValue() method. The computeValue() method is abstract in all of these classes, so it's mandatory when you define your own class. You'll need to call the protected bind() method from the parent abstract class, and the only place to do that is generally the constructor.

The computeValue() method is also protected. It's called from the public get() method, and it returns the data type encapsulated by the Binding class. So a class extending IntegerBinding will return int from both its get() and computeValue() methods.

This is very important to understand: The Binding itself is all about linking Observable values and Properties, but the computeValue() method is concerned about the underlying data type of the binding. It can calculate its return value from anywhere, and it generally deals with normal Java data types and classes.

An Example

Now, let's look at an example:

public class CustomBindingDemo extends Application {

    public static void main(String[] args) {
        launch();
    }

    @Override
    public void start(Stage stage) throws IOException {
        Scene scene = new Scene(createContent(), 620, 340);
        stage.setScene(scene);
        stage.show();
    }

    private Region createContent() {
        ObjectProperty<Integer> number1 = new SimpleObjectProperty<>(100);
        ObjectProperty<Integer> number2 = new SimpleObjectProperty<>(30);
        BooleanProperty evensOnly = new SimpleBooleanProperty(false);
        Label label1 = new Label();
        label1.textProperty().bind(number1.asString());
        Label label2 = new Label();
        label2.textProperty().bind(number2.asString());posts
        Label results = new Label();
        results.textProperty().bind(new CustomIntegerBinding(number1, number2, evensOnly).asString());
        HBox labelBox = new HBox(10,
                new Label("Number 1:"), label1,
                new Label("Number2: "), label2,
                new Label("Results: "), results);
        Button button1 = new Button("Increase Value 1");
        button1.setOnAction(evt -> number1.set(number1.get() + 1));
        Button button2 = new Button("Increase Value 2");
        button2.setOnAction(evt -> number2.set(number2.get() + 1));
        CheckBox checkBox = new CheckBox("Evens Only");
        evensOnly.bind(checkBox.selectedProperty());
        HBox controlBox = new HBox(5, button1, button2, checkBox);
        VBox vBox = new VBox(40, labelBox, controlBox);
        vBox.setPadding(new Insets(30));
        return vBox;
    }
}

class CustomIntegerBinding extends IntegerBinding {

    private final ObservableObjectValue<Integer> property1;
    private final ObservableObjectValue<Integer> property2;
    private final ObservableBooleanValue evenOnly;
    private int divisor = 1;

    public CustomIntegerBinding(ObservableObjectValue<Integer> property1, ObservableObjectValue<Integer> property2, ObservableBooleanValue evenOnly) {
        super.bind(property1, property2, evenOnly);
        this.property1 = property1;
        this.property2 = property2;
        this.evenOnly = evenOnly;
    }

    @Override
    protected int computeValue() {
        int result = (property1.get() + property2.get()) / divisor;
        System.out.println("computing " + property1.get() + " " + property2.get() + " divisor: " + divisor + " result: " + result);
        divisor++;
        if (evenOnly.get()) {
            return ((result % 2) == 0) ? result : 0;
        }
        return result;
    }
}

This is a bit goofy, and it certainly doesn't do anything too useful, but it does demonstrate all the key points you need to understand about custom bindings. When it runs, it looks like this:

and the console output looks like this:

computing 100 30 divisor: 1 result: 130
computing 100 30 divisor: 2 result: 65
computing 101 30 divisor: 3 result: 43
computing 102 30 divisor: 4 result: 33
computing 102 31 divisor: 5 result: 26
computing 102 32 divisor: 6 result: 22
computing 102 33 divisor: 7 result: 19
computing 102 33 divisor: 8 result: 16
computing 103 33 divisor: 9 result: 15
computing 104 33 divisor: 10 result: 13
computing 105 33 divisor: 11 result: 12

The Layout Code

Here we have three Property variables instantiated, which together are the Model for this application. Two are Integer properties used as counters, and the third is a Boolean property. So that we can see the results, we have a set of Labels in a row, the first two of which are bound to our counter properties, and the last is bound to our custom binding.

There are two Buttons and a CheckBox in a second row. Each Button increments one of the counter properties, and the CheckBox is bound to the Boolean property.

The Custom Binding

This custom Binding extends IntegerBinding, so its get() and computeValue() are going to return int. Since this is an externally declared class, we need to create fields for all of the dependency properties, and they need to be passed in the constructor. That's pretty much all that the constructor does; initialize the fields and call super.bind().

The call to super.bind() is going to register each of these properties with IntegerBinding so that they are monitored and will invalidate the Binding when one of them changes. This invalidation will trigger whatever Properties that this Binding is bound to to call the get() method, which will in turn call the computeValue() method.

There's also a private int field in the Binding called divisor. This is there to show that this is just an ordinary class, and computeValue() is just an ordinary method like any other.

What does computeValue() do? Basically, it adds the current values of both Integer properties together, and then divides them by the divisor, which it then increments by one. If the Boolean property is true then it checks to see if the result is even or odd, and if it's odd, it returns zero instead.

About Invalidation

At this point we need to talk about Invalidation and how it relates to Bindings.

What is it?

Every Observable has two data elements: The observed value and a Valid boolean. The Valid boolean signals whether or not the observed value has changed since the last time it was accessed, with true meaning that the last value accessed is still valid. When you set a listener on an Observable, what you're really doing is asking to be notified whenever the Valid value changes to "false". In other words, we're listening for when the value becomes "invalid" or, if you like, has been "invalidated".

Resetting Validation

This is super important: The only way to re-validate an Observable is to call the get() method of the Observable.

Think about those Labels in the sample code. They are bound to the IntegerProperties. There's a lot of functionality that we don't see (or really care about), behind Label. It needs to take the data from its Text property and turn it into pixels on the screen. Somewhere in there, there's going to be an InvalidationListener on that Text property, and that listener is going to call the property's get() method.

In turn, the property is going to call the binding's get() method, which in turn is going to call the get() method of the IntegerProperty. And all three elements are going to have their Valid field set to true.

Invalidating an Observable

A property can become invalidated in two ways: The set() method can be called on it or the Observable that it's been bound to has become invalidated. Since a bound Property cannot be set(), only one of these two reasons can ever apply to a Property at any given time.

Bindings can only become invalidated when one of their bound dependencies becomes invalidated. In turn, any Observables that are bound to this Binding will also become invalidated.

What you're seeing is that calling super.bind() in your custom Binding simply creates an InvalidationListener on each bound dependency which does nothing except invalidate your custom Binding. Any InvalidationListener on your Binding will be notified of the change.

This is super, super important: A Binding that's already invalidated cannot be invalidated again until it's reset.

The Big "Gotcha" With Custom Bindings

While it's true that the computeValue() method of a Binding can perform its calculation any way it wants and doesn't have to use any value from its bound dependencies, you really need to make sure that you call the get() method of every bound dependency inside computeValue().

Why?

Because you need to re-validate all of those bound dependencies. The InvalidationListeners are only going to trigger once when the Observable is invalidated. If it's not re-validated before its value is changed again, it's already invalidated and won't trigger the InvalidationListeners a second time.

Everyone who's created enough custom Bindings has fallen into this trap at least once. It usually happens when you have Bindings dependent on other Bindings so that it obscures where the problem is. Then, Poof! Three hours of your life are gone trying to figure out why the Binding updates sometimes but not others.

An Example of Not Re-validating

Here's the first example modified to remove all of the get() calls on the number2 property:

public class CustomBindingDemo2 extends Application {

    public static void main(String[] args) {
        launch();
    }

    @Override
    public void start(Stage stage) throws IOException {
        Scene scene = new Scene(createContent(), 620, 340);
        stage.setScene(scene);
        stage.show();
    }

    private Region createContent() {
        AtomicInteger number2Value = new AtomicInteger(30);
        ObjectProperty<Integer> number1 = new SimpleObjectProperty<>(100);
        ObjectProperty<Integer> number2 = new SimpleObjectProperty<>(number2Value.get());
        Label label1 = new Label();
        label1.textProperty().bind(number1.asString());
        Label results = new Label();
        results.textProperty().bind(new CustomIntegerBinding2(number1, number2).asString());
        HBox labelBox = new HBox(10,
                new Label("Number 1:"), label1,
                new Label("Results: "), results);
        Button button1 = new Button("Increase Value 1");
        button1.setOnAction(evt -> number1.set(number1.get() + 1));
        Button button2 = new Button("Increase Value 2");
        button2.setOnAction(evt -> number2.set(number2Value.incrementAndGet()));
        HBox controlBox = new HBox(5, button1, button2);
        VBox vBox = new VBox(40, labelBox, controlBox);
        vBox.setPadding(new Insets(30));
        return vBox;
    }
}

class CustomIntegerBinding2 extends IntegerBinding {

    private final ObservableObjectValue<Integer> property1;
    private int divisor = 1;

    public CustomIntegerBinding2(ObservableObjectValue<Integer> property1, ObservableObjectValue<Integer> property2) {
        super.bind(property1, property2);
        this.property1 = property1;
    }

    @Override
    protected int computeValue() {
        System.out.println("computing " + property1.get() + "divisor: " + divisor);
        return property1.get() / divisor++;
    }
}

The computeValue() method has been changed so that it only uses number1 and divisor, while the Binding itself still has a dependency on number2.

The Label showing the value of number2 has been removed because it was automatically calling get() on number2, and re-validating the Property. Finally, the action in button2 has been changed because it was calling number2.get() in order to change it. So a separate counter, number2Value was introduced so it's no longer necessary to call number2.get() in order to increment it.

Finally, the BooleanProperty has been removed since we're done with it.

Now, when you click on button1 the computeValue() method will be called every time. But after the first click of button2, which invalidates number2, it won't have any impact on the screen any more. The value in the Property will change, but it won't cause the custom binding to invalidate, because number2 has already been invalidated and there's no code in the program to re-validate it.

Binding Lists

Creating Bindings that calculate totals and averages, or which find the minimum or maximum of an ObservableList appears to be very difficult to do at first. It's nearly impossible if you're just using the Fluent API for binding, but actually quite easy with a custom Binding class.

Here we're going to calculate the total of an ObservableList<Integer> which is loaded into a ListView:

public class CustomBindingDemo3 extends Application {

    public static void main(String[] args) {
        launch();
    }

    @Override
    public void start(Stage stage) {
        Scene scene = new Scene(createContent(), 620, 340);
        stage.setScene(scene);
        stage.show();
    }

    private Region createContent() {
        Random numberGenerator = new Random();
        ObservableList<Integer> theList = FXCollections.observableArrayList();
        for (int x = 0; x < 5; x++) {
            theList.add(numberGenerator.nextInt(101));
        }
        ListView<Integer> listView = new ListView<>();
        listView.setItems(theList);
        Label results = new Label("");
        results.textProperty().bind(new CustomIntegerBinding3(theList).asString());
        HBox labelBox = new HBox(10, new Label("Total: "), results);
        Button button1 = new Button("Add Value");
        button1.setOnAction(evt -> theList.add(numberGenerator.nextInt(101)));
        VBox vBox = new VBox(10, listView, labelBox, button1);
        vBox.setPadding(new Insets(30));
        return vBox;
    }
}

class CustomIntegerBinding3 extends IntegerBinding {

    ObservableList<Integer> theList;

    public CustomIntegerBinding3(ObservableList<Integer> theList) {
        super.bind(theList);
        this.theList = theList;
    }

    @Override
    protected int computeValue() {
        System.out.println("computing " + theList.size());
        return theList.stream().reduce(0, Integer::sum);
    }
}

It looks something like this:

On the screen we have a ListView, a couple of Labels and a Button. The Button generates a new random number and adds it to the ObservableList. One of the Labels is bound to a custom Binding that calculates the total of values in the ObservableList. So when the Button is clicked, the ObservableList becomes invalidated, which invalidates the custom Binding and triggers the Label to call CustomIntegerBinding3.get(), which invokes its computeValue() method.

The calculation inside computeValue() is trivial; stream through the List and add up all the values.

Custom Bindings as Anonymous Inner Classes

This is probably the most common way that you'll use custom Bindings.

Anonymous Inner Classes have the advantage that you can access any variable or field which is available in the scope in which they are created, but the limitation that you can't use a constructor with parameters. For custom Bindings, you still need to implement the default constructor because you have to call super.bind().

Here's the previous List binding example, but rewritten as an anonymous inner class:

public class CustomBindingDemo4 extends Application {

    public static void main(String[] args) {
        launch();
    }

    @Override
    public void start(Stage stage) {
        Scene scene = new Scene(createContent(), 620, 340);
        stage.setScene(scene);
        stage.show();
    }

    private Region createContent() {
        Random numberGenerator = new Random();
        ObservableList<Integer> theList = FXCollections.observableArrayList();
        for (int x = 0; x < 5; x++) {
            theList.add(numberGenerator.nextInt(101));
        }
        IntegerBinding customListBinding = new IntegerBinding() {
            {
                super.bind(theList);
            }

            @Override
            protected int computeValue() {
                System.out.println("computing " + theList.size());
                return theList.stream().reduce(0, Integer::sum);
            }
        };
        ListView<Integer> listView = new ListView<>();
        listView.setItems(theList);
        Label results = new Label("");
        results.textProperty().bind(customListBinding.asString());
        HBox labelBox = new HBox(10, new Label("Total: "), results);
        Button button1 = new Button("Add Value");
        button1.setOnAction(evt -> theList.add(numberGenerator.nextInt(101)));
        VBox vBox = new VBox(10, listView, labelBox, button1);
        vBox.setPadding(new Insets(30));
        return vBox;
    }
}

Once again, it's fairly trivial and looks almost the same as the external custom Binding. There's no need to create a field for ObservableList, since it's available in the scope in which the Binding is created, so it can be directly referenced.

There is the slightly strange looking hanging {}, which is the Java way of defining default constructors for anonymous inner classes, and it does nothing other than call super.bind() to set theList as a bound dependency for the Binding.

Something to Watch Out For

Since anonymous inner classes have access to all the fields and local variables in their scope, it can be very tempting to just access any of these in computeValue(). However, if any of those fields or variables are mutable and they are NOT set as bound dependencies for the Binding, then changes in them will NOT trigger invalidation of your Binding.

Changes to those variables will be reflected in the value returned by computeValue() the next time that it is called, but that will only happen when one of the bound dependencies becomes invalidated.