Class JTableBinding<E,SS,TS>
- java.lang.Object
-
- org.jdesktop.beansbinding.Binding<SS,SV,TS,TV>
-
- org.jdesktop.beansbinding.AutoBinding<SS,java.util.List<E>,TS,java.util.List>
-
- org.jdesktop.swingbinding.JTableBinding<E,SS,TS>
-
- Type Parameters:
E
- the type of elements in the sourceList
SS
- the type of source object (on which the source property resolves toList
)TS
- the type of target object (on which the target property resolves toJTable
)
public final class JTableBinding<E,SS,TS> extends AutoBinding<SS,java.util.List<E>,TS,java.util.List>
Binds aList
of objects to act as the rows of aJTable
. Each object in the sourceList
represents one row in theJTable
. Mappings from properties of the source objects to columns are created by addingColumnBindings
to aJTableBinding
. Instances ofJTableBinding
are obtained by calling one of thecreateJTableBinding
methods in theSwingBindings
class.Here is an example of creating a binding from a
List
ofPerson
objects to aJTable
:// create the person List List
people = createPersonList(); // create the binding from List to JTable JTableBinding tb = SwingBindings.createJTableBinding(READ, people, jTable); // define the properties to be used for the columns BeanProperty firstNameP = BeanProperty.create("firstName"); BeanProperty lastNameP = BeanProperty.create("lastName"); BeanProperty ageP = BeanProperty.create("age"); // configure how the properties map to columns tb.addColumnBinding(firstNameP).setColumnName("First Name"); tb.addColumnBinding(lastNameP).setColumnName("Last Name"); tb.addColumnBinding(ageP).setColumnName("Age").setColumnClass(Integer.class); // realize the binding tb.bind(); The
JTable
target of aJTableBinding
acts as a live view of the objects in the sourceList
, regardless of the update strategy (the meaning of the update strategy is clarified later in this document).JTableBinding
listens to the properties specified for theColumnBindings
, for all objects in theList
, and updates the values displayed in theJTable
in response to change. All successful edits made toJTable
cell values are immediately committed back to corresponding objects in the sourceList
. If theList
is an instance ofObservableList
, then changes to theList
contents (such as adding, removing or replacing an object) are also reflected in theJTable
. Important: Changing the contents of a non-observableList
while it is participating in aJTableBinding
is unsupported, resulting in undefined behavior and possible exceptions.A cell in the
JTable
is editable for any given row and column when all of the following are true: the property specified for that column by itsColumnBinding
is writeable for the object representing that row, the"editable"
property of theJTableBinding
istrue
(the default), and the"editable"
property of theColumnBinding
istrue
(the default).JTableBinding
requires extra clarification on the operation of therefresh
andsave
methods and the meaning of the update strategy. The target property of aJTableBinding
is not the targetJTable
property provided in the constructor, but rather a private synthetic property representing theList
of objects to show in the targetJTable
. This synthetic property is readable/writeable only when theJTableBinding
is bound and the targetJTable
property is readable with anon-null
value.It is this private synthetic property on which the
refresh
andsave
methods operate; meaning that these methods simply cause syncing between the value of the sourceList
property and the value of the synthetic target property (representing theList
to be shown in the targetJTable
). These methods do not, therefore, have anything to do with refreshing or saving values in theJTable
. Likewise, the update strategy, which simply controls whenrefresh
andsave
are automatically called, also has nothing to do with refreshing or saving values in theJTable
.Note: At the current time, the
READ_WRITE
update strategy is not useful forJTableBinding
. To prevent unwanted confusion,READ_WRITE
is translated toREAD
byJTableBinding's
constructor.JTableBinding
works by installing a custom model on the targetJTable
, as appropriate, to represent the sourceList
. The model is installed on a targetJTable
with the first succesful call torefresh
with thatJTable
as the target. Subsequent calls torefresh
update the elements in this already-installed model. The model is uninstalled from a targetJTable
when either theJTableBinding
is unbound or when the targetJTable
property changes to no longer represent thatJTable
. Note: When the model is uninstalled from aJTable
, it is replaced with aDefaultTableModel
, in order to leave theJTable
functional.Some of the above is easier to understand with an example. Let's consider a
JTableBinding
(binding
), with update strategyREAD
, between a property representing aList
(listP
) and a property representing aJTable
(jTableP
).listP
andjTableP
both start off readable, referring to anon-null
List
andnon-null
JTable
respectively. Let's look at what happens for each of a sequence of events:Sequence Event Result 1 explicit call to binding.bind()
- synthetic target property becomes readable/writeable
-refresh()
is called
- model is installed on targetJTable
, representing list of objects2 listP
changes to a newList
- refresh()
is called
- model is updated with new list of objects3 jTableP
changes to a newJTable
- model is uninstalled from old JTable
4 explicit call to binding.refresh()
- model is installed on target JTable
, representing list of objects5 listP
changes to a newList
- refresh()
is called
- model is updated with new list of objects6 explicit call to binding.unbind()
- model is uninstalled from target JTable
Notice that in step 3, when the value of the
JTable
property changed, the newJTable
did not automatically get the model with the elements applied to it. A change to the target value should not cause anAutoBinding
to sync the target from the source. Step 4 forces a sync by explicitly callingrefresh
. Alternatively, it could be caused by any other action that results in arefresh
(for example, the source property changing value, or an explicit call tounbind
followed bybind
).ColumnBindings
are managed by theJTableBinding
. They are not to be explicitly bound, unbound, added to aBindingGroup
, or accessed in a way that is not allowed for a managed binding.BindingListeners
added to aColumnBinding
are notified at the time an editedJTable
value is to be committed back to the sourceList
. They receive notification of eithersynced
orsyncFailed
.BindingListeners
added to theJTableBinding
itself are also notified ofsync
andsyncFailed
for theJTableBinding's ColumnBindings
.In addition to binding the elements of a
JTable
, it is possible to bind to the selection of aJTable
. When binding to the selection of aJTable
backed by aJTableBinding
, the selection is always in terms of elements from the sourceList
. See the list of interesting swing properties in the package summary for more details.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
JTableBinding.ColumnBinding
ColumnBinding
represents a binding between a property of the elements in theJTableBinding's
sourceList
, and a column in the table.-
Nested classes/interfaces inherited from class org.jdesktop.beansbinding.AutoBinding
AutoBinding.UpdateStrategy
-
Nested classes/interfaces inherited from class org.jdesktop.beansbinding.Binding
Binding.SyncFailure, Binding.SyncFailureType, Binding.ValueResult<V>
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
JTableBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS,java.util.List<E>> sourceListProperty, TS targetObject, Property<TS,? extends javax.swing.JTable> targetJTableProperty, java.lang.String name)
Constructs an instance ofJTableBinding
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description JTableBinding.ColumnBinding
addColumnBinding(int index, Property<E,?> columnProperty)
Creates aColumnBinding
and inserts it at the given index into the list ofColumnBindings
maintained by thisJTableBinding
.JTableBinding.ColumnBinding
addColumnBinding(int index, Property<E,?> columnProperty, java.lang.String name)
Creates aColumnBinding
and inserts it at the given index into the list ofColumnBindings
maintained by thisJTableBinding
.JTableBinding.ColumnBinding
addColumnBinding(Property<E,?> columnProperty)
Creates aColumnBinding
and adds it to the end of the list ofColumnBindings
maintained by thisJTableBinding
.JTableBinding.ColumnBinding
addColumnBinding(Property<E,?> columnProperty, java.lang.String name)
Creates a namedColumnBinding
and adds it to the end of the list ofColumnBindings
maintained by thisJTableBinding
.protected void
bindImpl()
Called byBinding.bind()
to allow subclasses to initiate binding.JTableBinding.ColumnBinding
getColumnBinding(int index)
Returns theColumnBinding
with the given index in the list maintained by thisJTableBinding
.java.util.List<JTableBinding.ColumnBinding>
getColumnBindings()
Returns an unmodifiable copy of the list ofColumnBindings
maintained by thisJTableBinding
.boolean
isEditable()
Returns whether or not the cells of the table should be editable.JTableBinding.ColumnBinding
removeColumnBinding(int index)
Removes theColumnBinding
with the given index from the list maintained by thisJTableBinding
.boolean
removeColumnBinding(JTableBinding.ColumnBinding binding)
Removes the givenColumnBinding
from the list maintained by thisJTableBinding
.void
setEditable(boolean editable)
Sets whether or not the cells of the table should be editable.protected void
unbindImpl()
Called byBinding.unbind()
to allow subclasses to uninitiate binding.-
Methods inherited from class org.jdesktop.beansbinding.AutoBinding
getUpdateStrategy, paramString, sourceChangedImpl, targetChangedImpl
-
Methods inherited from class org.jdesktop.beansbinding.Binding
addBindingListener, addPropertyChangeListener, addPropertyChangeListener, bind, bindUnmanaged, firePropertyChange, getBindingListeners, getConverter, getName, getPropertyChangeListeners, getPropertyChangeListeners, getSourceNullValue, getSourceObject, getSourceProperty, getSourceUnreadableValue, getSourceValueForTarget, getTargetNullValue, getTargetObject, getTargetProperty, getTargetValueForSource, getValidator, isBound, isManaged, isSourceUnreadableValueSet, notifySynced, notifySyncFailed, refresh, refreshAndNotify, refreshAndNotifyUnmanaged, refreshUnmanaged, removeBindingListener, removePropertyChangeListener, removePropertyChangeListener, save, saveAndNotify, saveAndNotifyUnmanaged, saveUnmanaged, setConverter, setManaged, setSourceNullValue, setSourceObject, setSourceObjectUnmanaged, setSourceProperty, setSourceUnreadableValue, setTargetNullValue, setTargetObject, setTargetObjectUnmanaged, setTargetProperty, setValidator, throwIfBound, throwIfManaged, throwIfUnbound, toString, unbind, unbindUnmanaged, unsetSourceUnreadableValue
-
-
-
-
Constructor Detail
-
JTableBinding
protected JTableBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS,java.util.List<E>> sourceListProperty, TS targetObject, Property<TS,? extends javax.swing.JTable> targetJTableProperty, java.lang.String name)
Constructs an instance ofJTableBinding
.- Parameters:
strategy
- the update strategysourceObject
- the source objectsourceListProperty
- a property on the source object that resolves to theList
of elementstargetObject
- the target objecttargetJTableProperty
- a property on the target object that resolves to aJTable
name
- a name for theJTableBinding
- Throws:
java.lang.IllegalArgumentException
- if the source property or target property isnull
-
-
Method Detail
-
bindImpl
protected void bindImpl()
Description copied from class:Binding
Called byBinding.bind()
to allow subclasses to initiate binding. Subclasses typically need not installPropertyStateListeners
on the source property and target property as they will be notified by calls toBinding.sourceChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent)
andBinding.targetChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent)
when the source and target properties change respectively.- Overrides:
bindImpl
in classAutoBinding<SS,java.util.List<E>,TS,java.util.List>
- See Also:
Binding.unbindImpl()
-
unbindImpl
protected void unbindImpl()
Description copied from class:Binding
Called byBinding.unbind()
to allow subclasses to uninitiate binding.- Overrides:
unbindImpl
in classAutoBinding<SS,java.util.List<E>,TS,java.util.List>
- See Also:
Binding.bindImpl()
-
setEditable
public void setEditable(boolean editable)
Sets whether or not the cells of the table should be editable. The default for this property istrue
. See this paragraph in the class level documentation on editability.- Parameters:
editable
- whether or not the cells of the table should be editable
-
isEditable
public boolean isEditable()
Returns whether or not the cells of the table should be editable. The default for this property istrue
. See this paragraph in the class level documentation on editability.- Returns:
- whether or not the cells of the table should be editable
-
addColumnBinding
public JTableBinding.ColumnBinding addColumnBinding(Property<E,?> columnProperty)
Creates aColumnBinding
and adds it to the end of the list ofColumnBindings
maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Parameters:
columnProperty
- the property with which to derive cell values from the elements of the sourceList
- Returns:
- the
ColumnBinding
- Throws:
java.lang.IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
JTableBinding.ColumnBinding
-
addColumnBinding
public JTableBinding.ColumnBinding addColumnBinding(Property<E,?> columnProperty, java.lang.String name)
Creates a namedColumnBinding
and adds it to the end of the list ofColumnBindings
maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Parameters:
columnProperty
- the property with which to derive cell values from the elements of the sourceList
name
- a name for the column binding- Returns:
- the
ColumnBinding
- Throws:
java.lang.IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
JTableBinding.ColumnBinding
-
addColumnBinding
public JTableBinding.ColumnBinding addColumnBinding(int index, Property<E,?> columnProperty)
Creates aColumnBinding
and inserts it at the given index into the list ofColumnBindings
maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Parameters:
index
- the index at which to insert theColumnBinding
columnProperty
- the property with which to derive cell values from the elements of the sourceList
- Returns:
- the
ColumnBinding
- Throws:
java.lang.IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
JTableBinding.ColumnBinding
-
addColumnBinding
public JTableBinding.ColumnBinding addColumnBinding(int index, Property<E,?> columnProperty, java.lang.String name)
Creates aColumnBinding
and inserts it at the given index into the list ofColumnBindings
maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Parameters:
index
- the index at which to insert theColumnBinding
columnProperty
- the property with which to derive cell values from the elements of the sourceList
name
- a name for theColumnBinding
- Returns:
- the
ColumnBinding
- Throws:
java.lang.IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
JTableBinding.ColumnBinding
-
removeColumnBinding
public boolean removeColumnBinding(JTableBinding.ColumnBinding binding)
Removes the givenColumnBinding
from the list maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Parameters:
binding
- theColumnBinding
to remove- See Also:
addColumnBinding(Property, String)
-
removeColumnBinding
public JTableBinding.ColumnBinding removeColumnBinding(int index)
Removes theColumnBinding
with the given index from the list maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Parameters:
index
- the index of theColumnBinding
to remove- See Also:
addColumnBinding(Property, String)
-
getColumnBinding
public JTableBinding.ColumnBinding getColumnBinding(int index)
Returns theColumnBinding
with the given index in the list maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Parameters:
index
- the index of theColumnBinding
to return- Returns:
- the
ColumnBinding
at the given index - See Also:
addColumnBinding(Property, String)
-
getColumnBindings
public java.util.List<JTableBinding.ColumnBinding> getColumnBindings()
Returns an unmodifiable copy of the list ofColumnBindings
maintained by thisJTableBinding
.The list of
ColumnBindings
dictates the columns to be displayed in theJTable
, with aColumnBinding's
order in the list determining its table model index.- Returns:
- the list of
ColumnBindings
- See Also:
addColumnBinding(Property, String)
-
-