Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jgoodies.binding.beans
Class PropertyConnector

    java.lang.Object
      com.jgoodies.binding.beans.PropertyConnector

    public final class PropertyConnector

extends Object

Keeps two Java Bean properties in synch. If one of the bean properties fires a property change, this connector will set the other to the same value. If a bean property is read-only, the PropertyConnector will not listen to the other bean's property and so won't update the read-only property. And if a bean does not provide support for bound properties, it won't be observed. The properties must be single value bean properties as described by the Java Bean Secification.

Constraints: the properties must be type compatible, i. e. values returned by one reader must be accepted by the other's writer, and vice versa.

Examples:

     // Connects a ValueModel and a JFormattedTextField
     JFormattedTextField textField = new JFormattedTextField();
     textField.setEditable(editable);
     PropertyConnector connector =
         new PropertyConnector(valueModel, "value", textField, "value");
     connector.updateProperty2();

     // Connects the boolean property "selectable" with a component enablement
     JComboBox comboBox = new JComboBox();
     ...
     new PropertyConnector(mainModel, "selectable", comboBox, "enabled");

TODO: Consider adding an option to keep the two properties synchronized, even if one of them rejects or changes the value set. Background: The PropertyConnector has been designed to update a bean property if another one changes. In most situations this will synchronize both bean properties. However, it does not yet guarantee that both properties are kept synchronized; this is the case, if one property rejects values set, or changes the value set, for example to trim trailing spaces, or to turn a string to uppercase.

Version:
  $Revision: 1.5 $
Author:
  Karsten Lentzsch
See Also:
  `PropertyChangeEvent`, `PropertyChangeListener`, `PropertyDescriptor`

Constructor Summary
`PropertyConnector(Object bean1, String property1Name, Object bean2, String property2Name)` Constructs a PropertyConnector that synchronizes the two bound bean properties as specified by the given pairs of bean and associated property name.

Method Summary
`static void` | `connect(Object bean1, String property1Name, Object bean2, String property2Name)` Synchronizes the two bound bean properties as specified by the given pairs of bean and associated property name.
`Object` | `getBean1()` Returns the Java Bean that holds the first property.
`Object` | `getBean2()` Returns the Java Bean that holds the first property.
`String` | `getProperty1Name()` Returns the name of the first Java Bean property.
`String` | `getProperty2Name()` Returns the name of the second Java Bean property.
`void` | `release()` Removes the PropertyChangeHandler from the observed bean, if the bean is not null and if property changes are not observed.
`void` | `updateProperty1()` Reads the value of the second bean property and sets it as new value of the first bean property.
`void` | `updateProperty2()` Reads the value of the first bean property and sets it as new value of the second bean property.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### PropertyConnector

    public PropertyConnector(Object bean1,
                             String property1Name,
                             Object bean2,
                             String property2Name)

  Constructs a PropertyConnector that synchronizes the two bound bean properties as specified by the given pairs of bean and associated property name. If `Bean1#property1Name` changes it updates `Bean2#property2Name` and vice versa. If a bean does not provide support for bound properties, changes will not be observed. If a bean property is read-only, this connector will not listen to the other bean's property and so won't update the read-only property.

  In case you don't need the PropertyConnector instance, you better use the static method `connect(Object, String, Object, String)`. This constructor may confuse developers if you just use the side effects performed in the constructor; this is because it is quite unconventional to instantiate an object that you never use.

  Parameters:
    `bean1` - the bean that owns the first property
    `property1Name` - the name of the first property
    `bean2` - the bean that owns the second property
    `property2Name` - the name of the second property
  Throws:
    `NullPointerException` - if a bean or property name is `null`
    `IllegalArgumentException` - if the beans are identical and the property name are equal, or if both properties are read-only

Method Detail

### connect

    public static void connect(Object bean1,
                               String property1Name,
                               Object bean2,
                               String property2Name)

  Synchronizes the two bound bean properties as specified by the given pairs of bean and associated property name. If `Bean1#property1Name` changes it updates `Bean2#property2Name` and vice versa. If a bean does not provide support for bound properties, changes will not be observed. If a bean property is read-only, this connector will not listen to the other bean's property and so won't update the read-only property.

  Parameters:
    `bean1` - the bean that owns the first property
    `property1Name` - the name of the first property
    `bean2` - the bean that owns the second property
    `property2Name` - the name of the second property
  Throws:
    `NullPointerException` - if a bean or property name is `null`
    `IllegalArgumentException` - if the beans are identical and the property name are equal

### getBean1

    public Object getBean1()

  Returns the Java Bean that holds the first property.

  Returns:
    the Bean that holds the first property

### getBean2

    public Object getBean2()

  Returns the Java Bean that holds the first property.

  Returns:
    the Bean that holds the first property

### getProperty1Name

    public String getProperty1Name()

  Returns the name of the first Java Bean property.

  Returns:
    the name of the first property

### getProperty2Name

    public String getProperty2Name()

  Returns the name of the second Java Bean property.

  Returns:
    the name of the second property

### updateProperty1

    public void updateProperty1()

  Reads the value of the second bean property and sets it as new value of the first bean property.

  See Also:
    `updateProperty2()`

### updateProperty2

    public void updateProperty2()

  Reads the value of the first bean property and sets it as new value of the second bean property.

  See Also:
    `updateProperty1()`

### release

    public void release()

  Removes the PropertyChangeHandler from the observed bean, if the bean is not null and if property changes are not observed.

  To avoid memory leaks it is recommended to invoke this method if the connected beans live much longer than this connector. Once `#release` has been invoked this instance must not be used.

  As an alternative you may use event listener lists in the connected beans that are implemented using `WeakReference`.

  See Also:
    `WeakReference`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2006 JGoodies Karsten Lentzsch. All Rights Reserved.