Reply

JGoodies: Understanding Binding - Part 3

At 1:58 AM on Mar 11, 2005, R.J. Lorimer wrote:

Welcome back for the third edition in my 'JGoodies Bindings' entries, right here at www.Javalobby.org . Miss one of the first two tips? Check them out here:

JGoodies: Understanding Binding - Part 1
JGoodies: Understanding Binding - Part 2

So, what's next on the menu when it comes to discussing JGoodies Binding? The past two days I spent all my time showing how the actual binding process worked; how, by using custom 'adapters', it was possible to auto-magically tie beans and GUI components together. This tip is going to take that new-found knowledge, and take it to the next level. I'll be introducing some concepts that help developers control the binding process - namely presentation models, buffered value models, triggers, redirection, and change tracking.

Presentation Models

Presentation models are the third (and most complex) element in a chain of elements all designed to interact with bean values. The first I discussed in Tip 1 - the property adapter. The second I discussed later in tip 1, and in more detail in tip 2 - the bean adapter. The presentation model takes the concept of the bean adapter, but moves them above and beyond into a new level that is much more configurable and pluggable. While I won't be able to cover all the features available through extension of the com.jgoodies.binding.PresentationModel , I do plan to discuss the main advantages it brings to the table.

Presentation models, just like bean adapters, help you adapt a bean's properties to GUI widgets. However, in addition to that, the presentation model also allows for the changes being performed to not only be buffered - meaning they are deferred until you say they should be committed to the bean - but to also be observed to determine what changes (if any) were made. Finally, while I didn't cover it in bean adapters even though it is actually possible there as well, the bean can be swapped out for another.

Converting Code To Use Presentation Models

At the base level, presentation models plug right in where our bean adapter was - the only major difference being we call getModel as opposed to getValueModel :

// MyBean.java
import java.beans.PropertyChangeListener;
 
import com.jgoodies.binding.beans.*;
 
public class MyBean {
 // Note you don't HAVE to use this class - you can use
 // java.beans.PropertyChangeSupport if you want.
 private ExtendedPropertyChangeSupport changeSupport = new ExtendedPropertyChangeSupport(
   this);
 
 private boolean booleanValue;
 private String stringValue;
 
 public boolean getBooleanValue() {
  return booleanValue;
 }
 
 public void setBooleanValue(boolean newValue) {
  System.out.println("Boolean value set: " +newValue);
  boolean oldValue = booleanValue;
  booleanValue = newValue;
  changeSupport.firePropertyChange("booleanValue", oldValue, newValue);
 }
 
 public void addPropertyChangeListener(PropertyChangeListener x) {
  changeSupport.addPropertyChangeListener(x);
 }
 
 public void removePropertyChangeListener(PropertyChangeListener x) {
  changeSupport.removePropertyChangeListener(x);
 }
 
 public String getStringValue() {
  return stringValue;
 }
 
 public void setStringValue(String newValue) {
  System.out.println("String value set: "+  newValue);
  String oldValue = stringValue;
  this.stringValue = newValue;
  changeSupport.firePropertyChange("stringValue", oldValue, newValue);
 }
}
 
// Binding.java
 
import java.awt.GridLayout;
 
import javax.swing.*;
 
import com.jgoodies.binding.PresentationModel;
import com.jgoodies.binding.adapter.BasicComponentFactory;
import com.jgoodies.binding.beans.BeanAdapter;
import com.jgoodies.binding.value.ValueModel;
 
public class Binding {
 
 public static void main(String[] args) {
 
  MyBean bean = new MyBean();
  PresentationModel adapter = new PresentationModel(bean);
  
  ValueModel booleanModel = adapter.getModel("booleanValue");
  ValueModel stringModel = adapter.getModel("stringValue");
 
  JCheckBox box = BasicComponentFactory.createCheckBox(booleanModel, "Boolean Value");
  JTextField field = BasicComponentFactory.createTextField(stringModel);
  JFrame frame = new JFrame();
  frame.getContentPane().setLayout(new GridLayout(2,1));
  frame.getContentPane().add(box);
  frame.getContentPane().add(field);
  frame.pack();
  frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
  frame.setVisible(true);
 }
}

Ok, simple enough. Now on to the advantages.

Buffering

So what the heck is a buffered value model, and why do you care? Well, let's start talking real-world examples. You have a form on a page (let's say you created it with JGoodies Forms ), and you have an OK and Cancel button on the page (probably created using the JGoodies Forms Button Builder ) that when pressed will save the user's changes down to the bean. Uh oh. Wait a minute. If we're using these value model objects, the changes the user made will ALREADY be on the bean (incidentally, if you hadn't noticed already, when you check check-buttons, toggle toggle-buttons, or lose focus in a field you just typed in, those changes will be stuffed in to the bean immediately). So what do we do? Well, the solution with the binding framework is really quite elegant. By introducing the buffered value model (remember, we have a value model for each property), we can simply hold on to the user's change until something triggers (hey, notice the foreshadowing?) to the buffered value models that they should either commit or rollback the changes that the user made.

You may have guessed that the missing element that helps us trigger our buffered value models is the item I mentioned earlier - the com.jgoodies.binding.value.Trigger . I'll get into more details about triggers in a minute, but for the time being just assume it is a special object we can call commit or flush on to commit or... yes, you guessed it, flush the changes. So, how do we set up buffering? Well, it's actually quite easy. Step 1 - we create a trigger object and give it to our presentation model. Step 2 - we create buffered value models instead of regular value models. Step 3 - we call methods on the trigger object based on user behavior ( Note: I use the Forms button bar factory - see forms button builder tip (shameless plug) for more information):

import java.awt.GridLayout;
import java.awt.event.ActionListener;
 
import javax.swing.*;
 
import org.eclipse.swt.layout.GridData;
 
import com.jgoodies.binding.PresentationModel;
import com.jgoodies.binding.adapter.BasicComponentFactory;
import com.jgoodies.binding.beans.BeanAdapter;
import com.jgoodies.binding.value.Trigger;
import com.jgoodies.binding.value.ValueModel;
import com.jgoodies.forms.factories.ButtonBarFactory;
 
public class Binding {
 
 public static void main(String[] args) {
 
  MyBean bean = new MyBean();
  
  // create a new trigger for our presentation model, and store it in the presentation model.
  final Trigger trigger = new Trigger();
  PresentationModel adapter = new PresentationModel(bean, trigger);
  
  // Get buffered model objects.
  ValueModel booleanModel = adapter.getBufferedModel("booleanValue");
  ValueModel stringModel = adapter.getBufferedModel("stringValue");
  // creates a JCheckBox with the property adapter providing the underlying model.
  JCheckBox box = BasicComponentFactory.createCheckBox(booleanModel, "Boolean Value");
  JTextField field = BasicComponentFactory.createTextField(stringModel);
  
  // Create OK/Cancel buttons that fire the trigger
  JButton okButton = new JButton("OK");
  okButton.addActionListener(new ActionListener() {
   public void actionPerformed(java.awt.event.ActionEvent e) {
      // Print out a message so we can see the fruits of JGoodies' Labor.
      System.out.println("OK Button Pressed");
      trigger.triggerCommit();
   }  
  });
  
  JButton cancelButton = new JButton("Cancel");
  cancelButton.addActionListener(new ActionListener() {
   public void actionPerformed(java.awt.event.ActionEvent e) {
     trigger.triggerFlush();  
   }
  });
  
  JFrame frame = new JFrame();
  frame.getContentPane().setLayout(new GridLayout(3,1));
  frame.getContentPane().add(box);
  frame.getContentPane().add(field);
  // add the OK/Cancel buttons to the UI
  frame.getContentPane().add(ButtonBarFactory.buildOKCancelBar(okButton, cancelButton));
  frame.pack();
  frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
  frame.setVisible(true);
 }
}

Given the above code, here is what printed in my console when I 1.) Checked the check box, 2.) typed 'adsf' into the text field, and finally 3.) pressed 'OK'.

Remember, we have print statements in our bean for when the values are set. So what we are seeing is the values being set post-press of the OK button. Elementary, my dear watson.

More on Triggers

Technically speaking, the presentation model (which is the glue for all of this buffering stuff) doesn't care what object notifies the value models to commit or flush, as long as it is a value model. So, what does that mean? Well, it means that it doesn't have to be an OK/Cancel button 'actionPerformed' event that causes the trigger to fire - it could be the result of a property connector, or even just another field change. The point is, the trigger class is just a thin extension of the value model API that provides convenience methods that set the 'value' of the underlying value model. It is little different from doing this:

final ValueModel trigger = new ValueHolder();
PresentationModel model = new PresentationModel(myBean, trigger);
// ...
okButton.addActionListener(new ActionListener() {
 public void actionPerformed(ActionEvent evt) {
  trigger.setValue(Boolean.TRUE);
 }
});

So, what is my point? My point is - you can cause the trigger not just by manual wiring of action listeners, but also through an bean changes, gui behaviors, etc - it's up to your imagination.

Tracking Changes

Ok, back to real world examples. So you just implemented your OK/Cancel buttons above. Problem though. You want to be able to disable the OK button if the user hasn't made any actual changes. Actually, it's not a problem at all. All it requires is enabling the button based on the isChanged and isBuffering values of the PresentationModel object. Why are there two? Well, isChanged represents whether the underlying bean has actually been changed. isBuffering just implies that there are pending changes queued up. So, how can we enable/disable our OK/Cancel button based on these values? Things get kind of 'out of the box' here. While I've shown value models and property connectors when updating your bean - there is no reason we can't use them ON the PresentationModel (which, is in itself, a bean!) We can use our PropertyConnector class to update the OK button based on whether any changes are in the queue. Note, I'll use 'isBuffering' since we are using buffered models:

import java.awt.GridLayout;
import java.awt.event.ActionListener;
 
import javax.swing.*;
 
import org.eclipse.swt.layout.GridData;
 
import com.jgoodies.binding.PresentationModel;
import com.jgoodies.binding.adapter.BasicComponentFactory;
import com.jgoodies.binding.beans.BeanAdapter;
import com.jgoodies.binding.beans.PropertyConnector;
import com.jgoodies.binding.value.Trigger;
import com.jgoodies.binding.value.ValueModel;
import com.jgoodies.forms.factories.ButtonBarFactory;
 
public class Binding {
 
 public static void main(String[] args) {
 
  MyBean bean = new MyBean();
  
  // create a new trigger for our presentation model, and store it in the presentation model.
  final Trigger trigger = new Trigger();
  PresentationModel adapter = new PresentationModel(bean, trigger);
  
  // Get buffered model objects.
  ValueModel booleanModel = adapter.getBufferedModel("booleanValue");
  ValueModel stringModel = adapter.getBufferedModel("stringValue");
  // creates a JCheckBox with the property adapter providing the underlying model.
  JCheckBox box = BasicComponentFactory.createCheckBox(booleanModel, "Boolean Value");
  JTextField field = BasicComponentFactory.createTextField(stringModel);
  JButton okButton = new JButton("OK");
  okButton.addActionListener(new ActionListener() {
   public void actionPerformed(java.awt.event.ActionEvent e) {
      System.out.println("OK Button Pressed");
      trigger.triggerCommit();
   }  
  });
  
  // First, disable the OK button.
  okButton.setEnabled(false);
  // Note here that we wire the OK 'enabled' state to the presentation model 'buffering' state.
  PropertyConnector.connect(adapter, "buffering", okButton, "enabled");
  
  
  JButton cancelButton = new JButton("Cancel");
  cancelButton.addActionListener(new ActionListener() {
   public void actionPerformed(java.awt.event.ActionEvent e) {
     trigger.triggerFlush();  
   }
  });
  
  JFrame frame = new JFrame();
  frame.getContentPane().setLayout(new GridLayout(3,1));
  frame.getContentPane().add(box);
  frame.getContentPane().add(field);
  frame.getContentPane().add(ButtonBarFactory.buildOKCancelBar(okButton, cancelButton));
  frame.pack();
  frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
  frame.setVisible(true);
 }
}

This is one the more impressive examples of the binding framework, I think. The property connector class really presents a lot of opportunities for simple, powerful usage - it just requires a small amount of ingenuity on your part.

Redirection

Today's last subject is bean redirection. Ok - one more time, I need to ask you to go back to a real world example. You now have a GUI where the user can interact with multiple beans. We're kind of in a sticky situation though, because we bound all of these widgets to our bean, right? Wrong! They are bound to the value models, the value models are bound to our presentation model, and the presentation model is bound to our bean! So, what does that mean? It means swapping out the bean is a PIECE OF CAKE. Just call setBean on the PresentationModel, and walk away. No really, I mean it. That's it. Don't believe me? Ok, I'll go even further and implement a JList that allows the user to select from multiple beans, updates all fields and buttons on the form, and I'll do it all without writing any new listeners. First, here is a slightly modified 'MyBean.java' that has a new 'name' property (just for the sake of visual reference):

import java.beans.PropertyChangeListener;
 
import com.jgoodies.binding.beans.*;
 
public class MyBean {
 // Note you don't HAVE to use this class - you can use
 // java.beans.PropertyChangeSupport if you want.
 private ExtendedPropertyChangeSupport changeSupport = new ExtendedPropertyChangeSupport(
   this);
 
 private String name;
 private boolean booleanValue;
 private String stringValue;
 
 public boolean getBooleanValue() {
  return booleanValue;
 }
 
 public void setBooleanValue(boolean newValue) {
  System.out.println("Boolean value set: " +newValue);
  boolean oldValue = booleanValue;
  booleanValue = newValue;
  changeSupport.firePropertyChange("booleanValue", oldValue, newValue);
 }
 
 public void addPropertyChangeListener(PropertyChangeListener x) {
  changeSupport.addPropertyChangeListener(x);
 }
 
 public void removePropertyChangeListener(PropertyChangeListener x) {
  changeSupport.removePropertyChangeListener(x);
 }
 
 public String getStringValue() {
  return stringValue;
 }
 
 public void setStringValue(String newValue) {
  System.out.println("String value set: "+  newValue);
  String oldValue = stringValue;
  this.stringValue = newValue;
  changeSupport.firePropertyChange("stringValue", oldValue, newValue);
 }
 
 public String getName() {
  return name;
 }
 
 public String toString() {
  return getName();   
 }
 
 public void setName(String newName) {
  String oldName = name;
  this.name = newName;
  changeSupport.firePropertyChange("name", oldName, newName);
 }
}

... and now here is our ComboBox selector combined with our existing form:

import java.awt.GridLayout;
import java.awt.event.ActionListener;
import java.util.ArrayList;
import java.util.List;
 
import javax.swing.*;
 
import org.eclipse.swt.layout.GridData;
 
import com.jgoodies.binding.PresentationModel;
import com.jgoodies.binding.adapter.BasicComponentFactory;
import com.jgoodies.binding.adapter.ComboBoxAdapter;
import com.jgoodies.binding.beans.BeanAdapter;
import com.jgoodies.binding.beans.PropertyAdapter;
import com.jgoodies.binding.beans.PropertyConnector;
import com.jgoodies.binding.list.SelectionInList;
import com.jgoodies.binding.value.Trigger;
import com.jgoodies.binding.value.ValueModel;
import com.jgoodies.forms.factories.ButtonBarFactory;
 
public class Binding {
 
 public static void main(String[] args) {
 
  List possibleValues = createBeans();
 
  final Trigger trigger = new Trigger();
  // set the presentation model up to the first bean.
  PresentationModel beanPresentationModel = new PresentationModel(
    possibleValues.get(0), trigger);
 
  // create a property adapter for the presentation model 'bean' property.
  ValueModel beanProperty = new PropertyAdapter(beanPresentationModel, "bean");
  // wire our new combobox up to that property adapter.
  JComboBox comboBox = new JComboBox(new ComboBoxAdapter(possibleValues,
    beanProperty));
 
  // Get buffered model objects.
  ValueModel nameModel = beanPresentationModel.getBufferedModel("name");
  ValueModel booleanModel = beanPresentationModel
    .getBufferedModel("booleanValue");
  ValueModel stringModel = beanPresentationModel
    .getBufferedModel("stringValue");
  // creates a JCheckBox with the property adapter providing the underlying
  // model.
  JLabel label = BasicComponentFactory.createLabel(nameModel);
  JCheckBox box = BasicComponentFactory.createCheckBox(booleanModel,
    "Boolean Value");
  JTextField field = BasicComponentFactory.createTextField(stringModel);
  JButton okButton = new JButton("OK");
  okButton.addActionListener(new ActionListener() {
   public void actionPerformed(java.awt.event.ActionEvent e) {
    System.out.println("OK Button Pressed");
    trigger.triggerCommit();
   }
  });
 
  // First, disable the OK button.
  okButton.setEnabled(false);
  // Note here that we wire the OK 'enabled' state to the presentation model
  // 'buffering' state.
  PropertyConnector.connect(beanPresentationModel, "buffering", okButton,
    "enabled");
 
  JButton cancelButton = new JButton("Cancel");
  cancelButton.addActionListener(new ActionListener() {
   public void actionPerformed(java.awt.event.ActionEvent e) {
    trigger.triggerFlush();
   }
  });
 
  JFrame frame = new JFrame();
  frame.getContentPane().setLayout(new GridLayout(5, 1));
  frame.getContentPane().add(comboBox);
  frame.getContentPane().add(label);
  frame.getContentPane().add(box);
  frame.getContentPane().add(field);
  frame.getContentPane().add(
    ButtonBarFactory.buildOKCancelBar(okButton, cancelButton));
  frame.pack();
  frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
  frame.setVisible(true);
 }
 
 /**
  * @return
  */
 private static List createBeans() {
  // create a couple beans.
  MyBean bean1 = new MyBean();
  bean1.setName("Bean 1");
  bean1.setBooleanValue(true);
  bean1.setStringValue("tweedle-dee");
  MyBean bean2 = new MyBean();
  bean2.setName("Bean 2");
  bean2.setBooleanValue(false);
  bean2.setStringValue("tweedle-dum");
  List possibleValues = new ArrayList();
  possibleValues.add(bean1);
  possibleValues.add(bean2);
  return possibleValues;
 }
}

That's it! Don't believe me? Try it! Essentially, every time the JComboBox is used (and the selection changes), it tells its value model to accept the newly selected value (one of the beans). It just so happens that its value model is the value model for the property 'bean' on our PresentationModel object. Our presentation model object, as you probably remember, is the glue for our entire bean form (including the buffering). Therefore, because of some genius encapsulation, everything 'just works'.

If you have read all 3 of my tips on JGoodies binding so far, consider yourself shotgun-trained in using it. While I certainly haven't shown nearly everything that is possible, nor have I laid down the perhaps best practices in each particular case, I have shown enough that I'm hoping most anyone who has read these can get a kick-start and start developing their own thoughts and ideas on how to apply this framework.

Don't worry, though. I'm not done with you yet. My next tip will be a free-for-all on everything else binding. There are still some advanced features, and quirky things that can be done that I didn't cover today. I'd like to 'pick up the pieces' as it were and try and show you a couple more things out there that are waiting to be used!

Until next time,

R.J. Lorimer
rj -at- javalobby.org
http://www.coffee-bytes.com