Class 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
)
List
of objects to act as the rows of a JTable
.
Each object in the source List
represents one row in the JTable
.
Mappings from properties of the source objects to columns are created by
adding ColumnBindings
to a JTableBinding
. Instances of JTableBinding
are obtained by
calling one of the createJTableBinding
methods in the SwingBindings
class.
Here is an example of creating a binding from a List
of Person
objects to a JTable
:
// 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 a JTableBinding
acts as a live view of
the objects in the source List
,
regardless of the update strategy (the meaning of the update strategy is
clarified later in this document). JTableBinding
listens to the properties specified for the ColumnBindings
,
for all objects in the List
, and updates the values
displayed in the JTable
in response to change. All successful
edits made to JTable
cell values are immediately committed back to
corresponding objects in the source List
. If the List
is an
instance of ObservableList
, then changes to the List
contents
(such as adding, removing or replacing an object) are also reflected in the
JTable
. Important: Changing the contents of a non-observable
List
while it is participating in a JTableBinding
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 its ColumnBinding
is writeable for the object representing that row,
the "editable"
property of the JTableBinding
is true
(the default), and the "editable"
property of the ColumnBinding
is true
(the default).
JTableBinding
requires
extra clarification on the operation of the
refresh
and save
methods and the meaning of the update
strategy. The target property of a JTableBinding
is not the
target JTable
property provided in the constructor, but rather a
private synthetic property representing the List
of objects to show
in the target JTable
. This synthetic property is readable/writeable
only when the JTableBinding
is bound and the target JTable
property is readable with a non-null
value.
It is this private synthetic property on which the refresh
and
save
methods operate; meaning that these methods simply cause syncing
between the value of the source List
property and the value of the
synthetic target property (representing the List
to be shown in the
target JTable
). These methods do not, therefore, have anything to do
with refreshing or saving values in the JTable
. Likewise, the update
strategy, which simply controls when refresh
and save
are
automatically called, also has nothing to do with refreshing or saving
values in the JTable
.
Note: At the current time, the READ_WRITE
update strategy
is not useful for JTableBinding
. To prevent unwanted confusion,
READ_WRITE
is translated to READ
by JTableBinding's
constructor.
JTableBinding
works by installing a custom model on the target
JTable
, as appropriate, to represent the source List
. The
model is installed on a target JTable
with the first succesful call
to refresh
with that JTable
as the target. Subsequent calls
to refresh
update the elements in this already-installed model.
The model is uninstalled from a target JTable
when either the
JTableBinding
is unbound or when the target JTable
property
changes to no longer represent that JTable
. Note: When the model is
uninstalled from a JTable
, it is replaced with a DefaultTableModel
,
in order to leave the JTable
functional.
Some of the above is easier to understand with an example. Let's consider
a JTableBinding
(binding
), with update strategy
READ
, between a property representing a List
(listP
)
and a property representing a JTable
(jTableP
). listP
and jTableP
both start off readable, referring to a non-null
List
and non-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 target JTable , representing list of objects
|
2 | listP changes to a new List |
- refresh() is called
- model is updated with new list of objects |
3 | jTableP changes to a new JTable |
- model is uninstalled from old JTable
|
4 | explicit call to binding.refresh() |
- model is installed on target JTable , representing list of objects
|
5 | listP changes to a new List |
- refresh() is called
- model is updated with new list of objects |
6 | 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 new JTable
did not
automatically get the model with the elements applied to it. A change to the
target value should not cause an AutoBinding
to sync the target from
the source. Step 4 forces a sync by explicitly calling refresh
.
Alternatively, it could be caused by any other action that results
in a refresh
(for example, the source property changing value, or an
explicit call to unbind
followed by bind
).
ColumnBindings
are managed by the JTableBinding
. They are not
to be explicitly bound, unbound, added to a BindingGroup
, or accessed
in a way that is not allowed for a managed binding. BindingListeners
added to a ColumnBinding
are notified at the time an edited JTable
value
is to be committed back to the source List
. They receive notification of either
synced
or syncFailed
. BindingListeners
added to the
JTableBinding
itself are also notified of sync
and syncFailed
for the JTableBinding's ColumnBindings
.
In addition to binding the elements of a JTable
, it is possible to
bind to the selection of a JTable
. When binding to the selection of a JTable
backed by a JTableBinding
, the selection is always in terms of elements
from the source List
. See the list of
interesting swing properties in the package summary for more details.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionfinal class
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 -
Method Summary
Modifier and TypeMethodDescriptionaddColumnBinding
(int index, Property<E, ?> columnProperty) Creates aColumnBinding
and inserts it at the given index into the list ofColumnBindings
maintained by thisJTableBinding
.addColumnBinding
(int index, Property<E, ?> columnProperty, String name) Creates aColumnBinding
and inserts it at the given index into the list ofColumnBindings
maintained by thisJTableBinding
.addColumnBinding
(Property<E, ?> columnProperty) Creates aColumnBinding
and adds it to the end of the list ofColumnBindings
maintained by thisJTableBinding
.addColumnBinding
(Property<E, ?> columnProperty, 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.getColumnBinding
(int index) Returns theColumnBinding
with the given index in the list maintained by thisJTableBinding
.Returns an unmodifiable copy of the list ofColumnBindings
maintained by thisJTableBinding
.boolean
Returns whether or not the cells of the table should be editable.removeColumnBinding
(int index) Removes theColumnBinding
with the given index from the list maintained by thisJTableBinding
.boolean
removeColumnBinding
(JTableBinding<E, SS, TS>.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
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 Details
-
JTableBinding
protected JTableBinding(AutoBinding.UpdateStrategy strategy, SS sourceObject, Property<SS, List<E>> sourceListProperty, TS targetObject, Property<TS, ? extends JTable> targetJTableProperty, 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:
IllegalArgumentException
- if the source property or target property isnull
-
-
Method Details
-
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. -
unbindImpl
protected void unbindImpl()Description copied from class:Binding
Called byBinding.unbind()
to allow subclasses to uninitiate binding.- Overrides:
unbindImpl
in classAutoBinding<SS,
List<E>, TS, List> - See Also:
-
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
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:
IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
-
addColumnBinding
public JTableBinding<E,SS, addColumnBindingTS>.ColumnBinding (Property<E, ?> columnProperty, 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:
IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
-
addColumnBinding
public JTableBinding<E,SS, addColumnBindingTS>.ColumnBinding (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:
IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
-
addColumnBinding
public JTableBinding<E,SS, addColumnBindingTS>.ColumnBinding (int index, Property<E, ?> columnProperty, 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:
IllegalArgumentException
- ifcolumnProperty
isnull
- See Also:
-
removeColumnBinding
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:
-
removeColumnBinding
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:
-
getColumnBinding
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:
-
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:
-