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.list
Class ListModelHolder

    java.lang.Object
      com.jgoodies.binding.beans.Model
          com.jgoodies.binding.list.ListModelHolder

All Implemented Interfaces:
  Observable, Serializable, ListModel

Direct Known Subclasses:
  SelectionInListModel

    public class ListModelHolder

extends Model
implements ListModel

A ListModel implementation that delegates to a ListModel held by a ValueModel.

Imporant Note: If you change the ListModel instance, either by calling `#setListModel(ListModel)` or by setting a new value to the underlying list holder, you must ensure that the list holder throws a PropertyChangeEvent whenever the instance changes. This event is used to remove a ListDataListener from the old ListModel instance and is later used to add it to the new ListModel instance. It is easy to violate this constraint, just because Java's standard PropertyChangeSupport helper class that is used by many beans, checks a changed property value via `#equals`, not `==`. For example, if you change the SelectionInList's list model from an empty list `L1` to another empty list instance `L2`, the PropertyChangeSupport won't generate a PropertyChangeEvent, and so, the SelectionInList won't know about the change, which may lead to unexpected behavior.

This class provides public convenience methods for firing ListDataEvents, see the methods `#fireContentsChanged`, `#fireIntervalAdded`, and `#fireIntervalRemoved`. These are automatically invoked if the list holder holds a ListModel that fires these events. If on the other hand the underlying List or ListModel does not fire a required ListDataEvent, you can use these methods to notify presentations about a change. It is recommended to avoid sending duplicate ListDataEvents; hence check if the underlying ListModel fires the necessary events or not. Typically an underlying ListModel will fire the add and remove events; but often it'll lack an event if the (selected) contents has changed.

The current class name "ListModelHolder" and accessor #getListModelHolder may confuse users: what's the difference between the class (a ListModel) and its list model holder (a ValueModel)?

TODO: Find a better name and provide a transition to the new class name. I consider using "IndirectListModel" as the new name. The Binding 1.2 may offer the new class and keep the old as deprecated version. In the Binding 1.3 (or 2.0) the deprecated class can be removed.

Since:
  1.1
Version:
  $Revision: 1.9 $
Author:
  Karsten Lentzsch
See Also:
  `ListHolder`, `SelectionInListModel`, Serialized Form

Field Summary
`protected ListDataListener` | `listDataChangeHandler` Holds the change handler that fires changes is the ListModel changes.
`protected ListModel` | `listModel` Holds a copy of the listModelHolder's value.
`static String` | `PROPERTYNAME_LIST_MODEL` The name of the bound read-write listModel property.
`static String` | `PROPERTYNAME_LIST_MODEL_HOLDER` The name of the bound read-write listModelHolder property.

Constructor Summary
`ListModelHolder()` Constructs a ListModelHolder with an empty initial ArrayListModel.
`ListModelHolder(ListModel listModel)` Constructs a ListModelHolder on the given ListModel.
`ListModelHolder(ValueModel listModelHolder)` Constructs a ListModelHolder on the given ListModel.

Method Summary
`void` | `addListDataListener(ListDataListener l)` Adds a listener to the list that's notified each time a change to the data model occurs.
`protected ListDataListener` | `createListDataChangeHandler()` Creates and returns the ListDataListener used to observe changes in the underlying ListModel.
`void` | `fireContentsChanged(int index0, int index1)` Notifies all registered ListDataListeners that the contents of one or more list elements has changed.
`void` | `fireIntervalAdded(int index0, int index1)` Notifies all registered ListDataListeners that one or more elements have been added to this SelectionInList's List/ListModel.
`void` | `fireIntervalRemoved(int index0, int index1)` Notifies all registered ListDataListeners that one or more elements have been removed from this SelectionInList's List/ListModel.
`protected void` | `fireListChanged(int oldLastIndex, int newLastIndex)` Notifies all registered ListDataListeners that this ListModel has changed from an old list to a new list content.
`Object` | `getElementAt(int index)` Returns the value at the specified index.
`ListDataListener[]` | `getListDataListeners()` Returns an array of all the list data listeners registered on this `SelectionInList`.
`ListModel` | `getListModel()` Returns the contents of the list model holder.
`ValueModel` | `getListModelHolder()` Returns the ValueModel that holds the ListModel we delegate to.
`int` | `getSize()` Returns the length of the list, `0` if the list model is `null`.
`protected int` | `getSize(ListModel aListOrNull)` Returns the lists size or 0 if the list is null.
`boolean` | `isEmpty()` Checks and answers if the ListModel is empty or `null`.
`void` | `removeListDataListener(ListDataListener l)` Removes a listener from the list that's notified each time a change to the data model occurs.
`void` | `setListModel(ListModel newListModel)` Sets the given list model as value of the list holder.
`void` | `setListModelHolder(ValueModel newListModelHolder)` Sets a new ListModel holder.
`protected void` | `updateListModel(ListModel oldListModel, ListModel newListModel)` Removes the list data change handler from the old list in case it is not `null` and adds it to new one in case it is a not `null`.

Methods inherited from class com.jgoodies.binding.beans.Model
`addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, equals, fireMulticastPropertyChange, fireMultiplePropertiesChanged, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener`

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

Field Detail

### PROPERTYNAME_LIST_MODEL

    public static final String PROPERTYNAME_LIST_MODEL

  The name of the bound read-write listModel property.

  See Also:
    Constant Field Values

### PROPERTYNAME_LIST_MODEL_HOLDER

    public static final String PROPERTYNAME_LIST_MODEL_HOLDER

  The name of the bound read-write listModelHolder property.

  See Also:
    Constant Field Values

### listModel

    protected ListModel listModel

  Holds a copy of the listModelHolder's value. Used as the old ListModel when the listModelHolder's value changes. Required because a ValueModel may use `null` as old value, but this ListModelHolder must know about the old and the new ListModel.

### listDataChangeHandler

    protected final ListDataListener listDataChangeHandler

  Holds the change handler that fires changes is the ListModel changes.

Constructor Detail

### ListModelHolder

    public ListModelHolder()

  Constructs a ListModelHolder with an empty initial ArrayListModel.

### ListModelHolder

    public ListModelHolder(ListModel listModel)

  Constructs a ListModelHolder on the given ListModel.

  Parameters:
    `listModel` - the initial ListModel

### ListModelHolder

    public ListModelHolder(ValueModel listModelHolder)

  Constructs a ListModelHolder on the given ListModel.

  Constraints: 1) The listModelHolder must hold instances of ListModel and 2) must report a value change whenever the value's identity changes. Note that many bean properties don't fire a PropertyChangeEvent if the old and new value are equal - and so would break this constraint. If you provide a ValueHolder, enable its identityCheck feature during construction. If you provide an adapted bean property from a bean that extends the JGoodies `Model` class, you can enable the identity check feature in the methods `#firePropertyChange` by setting the trailing boolean parameter to `true`.

  Parameters:
    `listModelHolder` - provides the ListModel
  Throws:
    `NullPointerException` - if the listModelHolder is `null`
    `IllegalArgumentException` - if the listModelHolder is a ValueHolder that doesn't check the identity when changing its value
    `ClassCastException` - if the listModelHolder contents is not an instance of ListModel

Method Detail

### getListModel

    public final ListModel getListModel()

  Returns the contents of the list model holder.

  Returns:
    the contents of the list model holder.
  See Also:
    `setListModel(ListModel)`

### setListModel

    public final void setListModel(ListModel newListModel)

  Sets the given list model as value of the list holder.

  Parameters:
    `newListModel` - the list model to be set as new list content
  See Also:
    `getListModel()`

### getListModelHolder

    public final ValueModel getListModelHolder()

  Returns the ValueModel that holds the ListModel we delegate to.

  Returns:
    the ValueModel that holds the ListModel we delegate to.

### setListModelHolder

    public final void setListModelHolder(ValueModel newListModelHolder)

  Sets a new ListModel holder. Does nothing if old and new holder are equal. Removes the list change handler from the old holder and adds it to the new one. The list data change handler is re-registered by invoking `#updateListModel`.

  TODO: Check and verify whether the list data registration update can be performed in one step after the listHolder has been changed - instead of remove the list data change handler, then changing the listHolder, and finally adding the list data change handler.

  Parameters:
    `newListModelHolder` - the ListModel holder to be set
  Throws:
    `NullPointerException` - if the new ListModel holder is `null`
    `IllegalArgumentException` - if the new ListModel holder is a ValueHolder that has the identityCheck feature disabled
    `ClassCastException` - if the new ListModel holder's value is not a ListModel

### isEmpty

    public final boolean isEmpty()

  Checks and answers if the ListModel is empty or `null`.

  Returns:
    true if the ListModel is empty or `null`, false otherwise

### getSize

    public final int getSize()

  Returns the length of the list, `0` if the list model is `null`.

  Specified by:
    `getSize` in interface `ListModel`
  Returns:
    the size of the list, `0` if the list model is `null`

### getElementAt

    public final Object getElementAt(int index)

  Returns the value at the specified index.

  Specified by:
    `getElementAt` in interface `ListModel`
  Parameters:
    `index` - the requested index
  Returns:
    the value at `index`
  Throws:
    `NullPointerException` - if the list model holder's content is null

### addListDataListener

    public final void addListDataListener(ListDataListener l)

  Adds a listener to the list that's notified each time a change to the data model occurs.

  Specified by:
    `addListDataListener` in interface `ListModel`
  Parameters:
    `l` - the `ListDataListener` to be added

### removeListDataListener

    public final void removeListDataListener(ListDataListener l)

  Removes a listener from the list that's notified each time a change to the data model occurs.

  Specified by:
    `removeListDataListener` in interface `ListModel`
  Parameters:
    `l` - the `ListDataListener` to be removed

### getListDataListeners

    public final ListDataListener[] getListDataListeners()

  Returns an array of all the list data listeners registered on this `SelectionInList`.

  Returns:
    all of this model's `ListDataListener`s, or an empty array if no list data listeners are currently registered
  See Also:
    `addListDataListener(ListDataListener)`, `removeListDataListener(ListDataListener)`

### fireContentsChanged

    public final void fireContentsChanged(int index0,
                                          int index1)

  Notifies all registered ListDataListeners that the contents of one or more list elements has changed. The changed elements are specified by the closed interval index0, index1 -- the end points are included. Note that index0 need not be less than or equal to index1.

  Parameters:
    `index0` - one end of the new interval
    `index1` - the other end of the new interval
  See Also:
    `ListModel`, `ListDataListener`, `ListDataEvent`

### fireIntervalAdded

    public final void fireIntervalAdded(int index0,
                                        int index1)

  Notifies all registered ListDataListeners that one or more elements have been added to this SelectionInList's List/ListModel. The new elements are specified by a closed interval index0, index1 -- the end points are included. Note that index0 need not be less than or equal to index1.

  Parameters:
    `index0` - one end of the new interval
    `index1` - the other end of the new interval
  See Also:
    `ListModel`, `ListDataListener`, `ListDataEvent`

### fireIntervalRemoved

    public final void fireIntervalRemoved(int index0,
                                          int index1)

  Notifies all registered ListDataListeners that one or more elements have been removed from this SelectionInList's List/ListModel. `index0` and `index1` are the end points of the interval that's been removed. Note that `index0` need not be less than or equal to `index1`.

  Parameters:
    `index0` - one end of the removed interval, including `index0`
    `index1` - the other end of the removed interval, including `index1`
  See Also:
    `ListModel`, `ListDataListener`, `ListDataEvent`

### createListDataChangeHandler

    protected ListDataListener createListDataChangeHandler()

  Creates and returns the ListDataListener used to observe changes in the underlying ListModel. It is re-registered in `#updateListModel`.

  Returns:
    the ListDataListener that handles changes in the underlying ListModel

### updateListModel

    protected void updateListModel(ListModel oldListModel,
                                   ListModel newListModel)

  Removes the list data change handler from the old list in case it is not `null` and adds it to new one in case it is a not `null`. Also fires a property change for listModel and a ListModel update event.

  Parameters:
    `oldListModel` - the old ListModel
    `newListModel` - the new ListModel

### fireListChanged

    protected final void fireListChanged(int oldLastIndex,
                                         int newLastIndex)

  Notifies all registered ListDataListeners that this ListModel has changed from an old list to a new list content. If the old and new list have the same size, a content change event is fired. Otherwise, two events are fired: a remove event for the old list's interval, and a add event for the new list's interval.

  This method is invoked by #updateList during the transition from an old List(Model) to a new List(Model).

  Parameters:
    `oldLastIndex` - the last index of the old list
    `newLastIndex` - the last index of the new list

### getSize

    protected final int getSize(ListModel aListOrNull)

  Returns the lists size or 0 if the list is null.

  Parameters:
    `aListOrNull` - a List or null
  Returns:
    the list's size or 0 if the list is null

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.