|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectorg.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>
E - the type of elements in the source ListSS - the type of source object (on which the source property resolves to List)TS - the type of target object (on which the target property resolves to JTable)public final class JTableBinding<E,SS,TS>
Binds a 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 | |
|---|---|
class |
JTableBinding.ColumnBinding
ColumnBinding represents a binding between a property of the elements
in the JTableBinding's source List, 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 | |
|---|---|
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 of JTableBinding. |
| Method Summary | |
|---|---|
JTableBinding.ColumnBinding |
addColumnBinding(int index,
Property<E,?> columnProperty)
Creates a ColumnBinding and inserts it at the given index into the list
of ColumnBindings maintained by this JTableBinding. |
JTableBinding.ColumnBinding |
addColumnBinding(int index,
Property<E,?> columnProperty,
java.lang.String name)
Creates a ColumnBinding and inserts it at the given index into the list
of ColumnBindings maintained by this JTableBinding. |
JTableBinding.ColumnBinding |
addColumnBinding(Property<E,?> columnProperty)
Creates a ColumnBinding and adds it to the end of the list of ColumnBindings
maintained by this JTableBinding. |
JTableBinding.ColumnBinding |
addColumnBinding(Property<E,?> columnProperty,
java.lang.String name)
Creates a named ColumnBinding and adds it to the end of the list of ColumnBindings
maintained by this JTableBinding. |
protected void |
bindImpl()
Called by Binding.bind() to allow subclasses to initiate binding. |
JTableBinding.ColumnBinding |
getColumnBinding(int index)
Returns the ColumnBinding with the given index in the list maintained
by this JTableBinding. |
java.util.List<JTableBinding.ColumnBinding> |
getColumnBindings()
Returns an unmodifiable copy of the list of ColumnBindings maintained
by this JTableBinding. |
boolean |
isEditable()
Returns whether or not the cells of the table should be editable. |
JTableBinding.ColumnBinding |
removeColumnBinding(int index)
Removes the ColumnBinding with the given index from the list maintained
by this JTableBinding. |
boolean |
removeColumnBinding(JTableBinding.ColumnBinding binding)
Removes the given ColumnBinding from the list maintained
by this JTableBinding. |
void |
setEditable(boolean editable)
Sets whether or not the cells of the table should be editable. |
protected void |
unbindImpl()
Called by Binding.unbind() to allow subclasses to uninitiate binding. |
| Methods inherited from class org.jdesktop.beansbinding.AutoBinding |
|---|
getUpdateStrategy, paramString, sourceChangedImpl, targetChangedImpl |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Constructor Detail |
|---|
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)
JTableBinding.
strategy - the update strategysourceObject - the source objectsourceListProperty - a property on the source object that resolves to the List of elementstargetObject - the target objecttargetJTableProperty - a property on the target object that resolves to a JTablename - a name for the JTableBinding
java.lang.IllegalArgumentException - if the source property or target property is null| Method Detail |
|---|
protected void bindImpl()
BindingBinding.bind() to allow subclasses to initiate binding.
Subclasses typically need not install PropertyStateListeners
on the source property and target property as they will be notified
by calls to Binding.sourceChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent) and Binding.targetChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent)
when the source and target properties change respectively.
bindImpl in class AutoBinding<SS,java.util.List<E>,TS,java.util.List>Binding.unbindImpl()protected void unbindImpl()
BindingBinding.unbind() to allow subclasses to uninitiate binding.
unbindImpl in class AutoBinding<SS,java.util.List<E>,TS,java.util.List>Binding.bindImpl()public void setEditable(boolean editable)
true.
See this paragraph in the class level
documentation on editability.
editable - whether or not the cells of the table should be editablepublic boolean isEditable()
true.
See this paragraph in the class level
documentation on editability.
public JTableBinding.ColumnBinding addColumnBinding(Property<E,?> columnProperty)
ColumnBinding and adds it to the end of the list of ColumnBindings
maintained by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
columnProperty - the property with which to derive cell values from the
elements of the source List
ColumnBinding
java.lang.IllegalArgumentException - if columnProperty is nullJTableBinding.ColumnBinding
public JTableBinding.ColumnBinding addColumnBinding(Property<E,?> columnProperty,
java.lang.String name)
ColumnBinding and adds it to the end of the list of ColumnBindings
maintained by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
columnProperty - the property with which to derive cell values from the
elements of the source Listname - a name for the column binding
ColumnBinding
java.lang.IllegalArgumentException - if columnProperty is nullJTableBinding.ColumnBinding
public JTableBinding.ColumnBinding addColumnBinding(int index,
Property<E,?> columnProperty)
ColumnBinding and inserts it at the given index into the list
of ColumnBindings maintained by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
index - the index at which to insert the ColumnBindingcolumnProperty - the property with which to derive cell values from the
elements of the source List
ColumnBinding
java.lang.IllegalArgumentException - if columnProperty is nullJTableBinding.ColumnBinding
public JTableBinding.ColumnBinding addColumnBinding(int index,
Property<E,?> columnProperty,
java.lang.String name)
ColumnBinding and inserts it at the given index into the list
of ColumnBindings maintained by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
index - the index at which to insert the ColumnBindingcolumnProperty - the property with which to derive cell values from the
elements of the source Listname - a name for the ColumnBinding
ColumnBinding
java.lang.IllegalArgumentException - if columnProperty is nullJTableBinding.ColumnBindingpublic boolean removeColumnBinding(JTableBinding.ColumnBinding binding)
ColumnBinding from the list maintained
by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
binding - the ColumnBinding to removeaddColumnBinding(Property, String)public JTableBinding.ColumnBinding removeColumnBinding(int index)
ColumnBinding with the given index from the list maintained
by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
index - the index of the ColumnBinding to removeaddColumnBinding(Property, String)public JTableBinding.ColumnBinding getColumnBinding(int index)
ColumnBinding with the given index in the list maintained
by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
index - the index of the ColumnBinding to return
ColumnBinding at the given indexaddColumnBinding(Property, String)public java.util.List<JTableBinding.ColumnBinding> getColumnBindings()
ColumnBindings maintained
by this JTableBinding.
The list of ColumnBindings dictates the columns to be displayed in the
JTable, with a ColumnBinding's order in the list determining its
table model index.
ColumnBindingsaddColumnBinding(Property, String)
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||