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.ideanest.swing
Class ActiveCollections

java.lang.Object
  |
  +--com.ideanest.swing.ActiveCollections
public class ActiveCollections
extends java.lang.Object

Provides adapters between base JDK collections and the JFC/Swing ListModel interface. This class consists exclusively of static methods that return wrappers backed by a specified collection but implementing the Swing ListModel interface.

To use, call the appropriate method to wrap your collection at the point it's created. You should wrap it immediately and never again refer to the backing collection, since only mutations that go through the wrapper will cause events to be fired. To put it another way, mutating the underlying collection directly will lead to inconsistent event reporting, and hence an inconsistent GUI (if used with Swing).

Once your collection is wrapped, you can use it as a normal collection. All standard methods are supported (depending on the wrapper you chose). Since the wrapper also implements the ListModel interface, you can pass it directly to any Swing component requiring such a model (e.g. JList, JComboBox (with the ComboListModelAdapter, etc). To avoid casting, interfaces combining the collection interfaces with the Swing ListModel are provided for your convenience. You can use these when declaring variables in your code.

The list model presented to Swing will be ordered according to the underlying collection's iterator. For ordered collections (lists, sorted sets) this is well defined and you'll get a consistent, expected order. For other kinds of collections, the order may change with each mutation. This will be reflected in the Swing presentation.

Note that any objects you derive from an active wrapper (including mutating iterators and subcollections) will also correctly cause events to be fired in the original collection they were derived from. You cannot, however, wrap the various collections returned by a Map, since those can be mutated by the original map, which is not in a wrapper.

The objects returned by methods in this class are:

  • not thread-safe
  • not cloneable (create a new collection instance using a copy-constructor instead, then wrap it in an active adapter)
  • serializable (but the listeners list will not be serialized)

Author:
Piotr Kaminski

Method Summary
static ActiveCollection activeCollection(java.util.Collection c)
          Returns an active version of the specified collection that fires ListDataEvents when the collection is mutated.
static ActiveList activeList(java.util.List list)
          Returns an active version of the specified list that fires ListDataEvents when the list is mutated.
static ActiveSet activeSet(java.util.Set c)
          Returns an active version of the specified set that fires ListDataEvents when the set is mutated.
static ActiveSortedSet activeSortedSet(java.util.SortedSet c)
          Returns an active version of the specified sorted set that fires ListDataEvents when the sorted set is mutated.
static ActiveCollection synchronizedActiveCollection(java.util.Collection c)
          Returns a synchronized active version of the specified collection that fires ListDataEvents when the collection is mutated.
static ActiveList synchronizedActiveList(java.util.List c)
          Returns a synchronized active version of the specified list that fires ListDataEvents when the list is mutated.
static ActiveSet synchronizedActiveSet(java.util.Set c)
          Returns a synchronized active version of the specified set that fires ListDataEvents when the set is mutated.
static ActiveSortedSet synchronizedActiveSortedSet(java.util.SortedSet c)
          Returns a synchronized active version of the specified sorted set that fires ListDataEvents when the set is mutated.
static ActiveCollection unmodifiableActiveCollection(ActiveCollection c)
          Returns an unmodifiable view of the specified active collection.
static ActiveList unmodifiableActiveList(ActiveList c)
          Returns an unmodifiable view of the specified active list.
static ActiveSet unmodifiableActiveSet(ActiveSet c)
          Returns an unmodifiable view of the specified active set.
static ActiveSortedSet unmodifiableActiveSortedSet(ActiveSortedSet c)
          Returns an unmodifiable view of the specified active sorted set.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

activeCollection

public static ActiveCollection activeCollection(java.util.Collection c)
Returns an active version of the specified collection that fires ListDataEvents when the collection is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or subcollections).

The returned collection does not pass the hashCode and equals operations through to the backing collection, but relies on Object's equals and hashCode methods. This is necessary to preserve the contracts of these operations in the case that the backing collection is a set or a list.

The returned collection will be serializable if the specified collection is serializable.

Parameters:
c - the collection for which an active version is to be returned
Returns:
an active version of the specified collection

activeList

public static ActiveList activeList(java.util.List list)
Returns an active version of the specified list that fires ListDataEvents when the list is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or sublists).

The returned list will be serializable if the specified list is serializable.

Parameters:
list - the list for which an active version is to be returned
Returns:
an active version of the specified list

activeSet

public static ActiveSet activeSet(java.util.Set c)
Returns an active version of the specified set that fires ListDataEvents when the set is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or subsets).

The returned set will be serializable if the specified set is serializable.

Parameters:
c - the set for which an active version is to be returned
Returns:
an active version of the specified set

activeSortedSet

public static ActiveSortedSet activeSortedSet(java.util.SortedSet c)
Returns an active version of the specified sorted set that fires ListDataEvents when the sorted set is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or subsorted sets).

The returned sorted set will be serializable if the specified sorted set is serializable.

Parameters:
c - the sorted set for which an active version is to be returned
Returns:
an active version of the specified sorted set

synchronizedActiveCollection

public static ActiveCollection synchronizedActiveCollection(java.util.Collection c)
Returns a synchronized active version of the specified collection that fires ListDataEvents when the collection is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or subcollections).

The returned collection will implement Lockable and will enforce mutual exclusion on all its operations. To maintain a lock on the collection for the duration of more than one operation, you should synchronize on its lock. This is absolutely required for iteration, for example: 

ActiveCollection bag = ActiveCollections.synchronizedActiveCollection(new ArrayList());
 bag.add("a");  bag.add("b");
 synchronized( ((Lockable) bag).getLock() ) {
   Iterator it = bag.iterator();
   while(it.hasNext()) {
     System.out.println(it.next());
   }
 }

The returned collection does not pass the hashCode and equals operations through to the backing collection, but relies on Object's equals and hashCode methods. This is necessary to preserve the contracts of these operations in the case that the backing collection is a set or a list.

The returned collection will be serializable if the specified collection is serializable.

Parameters:
c - the collection for which an active version is to be returned
Returns:
an active version of the specified collection

synchronizedActiveList

public static ActiveList synchronizedActiveList(java.util.List c)
Returns a synchronized active version of the specified list that fires ListDataEvents when the list is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or subcollections).

The returned list will implement Lockable and will enforce mutual exclusion on all its operations.

The returned list will be serializable if the specified collection is serializable.

Parameters:
c - the list for which a synchronized active version is to be returned
Returns:
an active version of the specified list

synchronizedActiveSet

public static ActiveSet synchronizedActiveSet(java.util.Set c)
Returns a synchronized active version of the specified set that fires ListDataEvents when the set is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or subcollections).

The returned set will implement Lockable and will enforce mutual exclusion on all its operations.

The returned set will be serializable if the specified collection is serializable.

Parameters:
c - the set for which a synchronized active version is to be returned
Returns:
an active version of the specified set

synchronizedActiveSortedSet

public static ActiveSortedSet synchronizedActiveSortedSet(java.util.SortedSet c)
Returns a synchronized active version of the specified sorted set that fires ListDataEvents when the set is mutated. Note that all mutation must take place through the active version, or through objects that it returns (i.e. through iterators or subcollections).

The returned sorted set will implement Lockable and will enforce mutual exclusion on all its operations.

The returned sorted set will be serializable if the specified collection is serializable.

Parameters:
c - the sorted set for which a synchronized active version is to be returned
Returns:
an active version of the specified sorted set

unmodifiableActiveCollection

public static ActiveCollection unmodifiableActiveCollection(ActiveCollection c)
Returns an unmodifiable view of the specified active collection. This method allows modules to provide users with "read-only" access to internal collections. Query operations on the returned collection "read through" to the specified collection, and attempts to modify the returned collection, whether direct or via its iterator, result in an UnsupportedOperationException.

The returned collection does not pass the hashCode and equals operations through to the backing collection, but relies on Object's equals and hashCode methods. This is necessary to preserve the contracts of these operations in the case that the backing collection is a set or a list.

The returned collection will be serializable if the specified collection is serializable. The returned collection will be lockable if the specified collection is lockable.

Parameters:
c - the active collection for which an unmodifiable view is to be returned
Returns:
an active unmodifiable view of the specified collection

unmodifiableActiveList

public static ActiveList unmodifiableActiveList(ActiveList c)
Returns an unmodifiable view of the specified active list. This method allows modules to provide users with "read-only" access to internal lists. Query operations on the returned list "read through" to the specified list, and attempts to modify the returned list, whether direct or via its iterator, result in an UnsupportedOperationException.

The returned list will be serializable if the specified list is serializable. The returned list will be lockable if the specified collection is lockable.

Parameters:
c - the active list for which an unmodifiable view is to be returned
Returns:
an active unmodifiable view of the specified list

unmodifiableActiveSet

public static ActiveSet unmodifiableActiveSet(ActiveSet c)
Returns an unmodifiable view of the specified active set. This method allows modules to provide users with "read-only" access to internal sets. Query operations on the returned set "read through" to the specified set, and attempts to modify the returned set, whether direct or via its iterator, result in an UnsupportedOperationException.

The returned set will be serializable if the specified set is serializable. The returned set will be lockable if the specified collection is lockable.

Parameters:
c - the active set for which an unmodifiable view is to be returned
Returns:
an active unmodifiable view of the specified set

unmodifiableActiveSortedSet

public static ActiveSortedSet unmodifiableActiveSortedSet(ActiveSortedSet c)
Returns an unmodifiable view of the specified active sorted set. This method allows modules to provide users with "read-only" access to internal sorted sets. Query operations on the returned sorted set "read through" to the specified sorted set, and attempts to modify the returned sorted set, whether direct or via its iterator, result in an UnsupportedOperationException.

The returned sorted set will be serializable if the specified sorted set is serializable. The returned sorted set will be lockable if the specified collection is lockable.

Parameters:
c - the active sorted set for which an unmodifiable view is to be returned
Returns:
an active unmodifiable view of the specified sorted set
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD