org.favabeans.base
Class CollectionFolder

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractList
              |
              +--org.favabeans.base.CollectionFolder

All Implemented Interfaces:

Collection, Facet, Faceted, Folder, List

Direct Known Subclasses:

ListFolder

public class CollectionFolder

extends AbstractList

implements Folder, Faceted

A CollectionFolder is a Folder Facet suitable for use with Collection primary objects.

This Facet creates an illusion of a List given a generic Collection. In so doing, we present some caveats:

• The List operations of this Facet apply to the ordering of the Collection primary object's elements as obtained from an iterator via Collection.iterator(); we call this the natural ordering of the elements.
• Mutating operations on the primary object may change the natural ordering. This Facet does not (and cannot) know whether a generic change event broadcast by the primary object is a result of changes made only through this Facet, so we re-apply the iteration every time the primary object changes (based on its Change Facet.
• The List.remove(int) operation calls Collection.remove(Object). If the primary object allows duplicates, this operation will remove an arbitrary object that Object.equals(Object) the method argument.
• The List.add(int, Object) operation calls Collection.add(Object) on the primary object.
• The List.set(int, Object) operation calls Collection.remove(Object) and then Collection.add(Object) on the primary object.

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

CollectionFolder(Object primaryObject)

Method Summary

void	add(int i, Object o)
void	addListDataListener(ListDataListener l)
void	addPropertyChangeListener(PropertyChangeListener l)
void	addPropertyChangeListener(String propertyName, PropertyChangeListener l)
protected Column[]	buildAdditionalColumns() Build and return a set of additional Column objects which are not obtainable via Bean introspection.
protected void	fireContentsChanged()
protected void	fireStateChanged()
Object	get(int i) Get the ith element, as defined by the primary object's natural ordering.
protected Collection	getCollection()
Column[]	getColumns() The columns of this Folder, represented as a set of Column objects.
Facet	getFacet(Type type) Obtain a Facet of the requested Type for this object.
Object	getPrimaryObject() Obtain the primary object of this Facet.
boolean	isMutable() Determine whether this Folder supports mutation.
boolean	isOrderingSemantic() Determine whether the ordering of this Folder is merely coincidental, based on the need to make up an ordering for the convenience of UI elements, or semantic, that is to say, of actual importance to the underlying domain object model.
Object	remove(int i) Remove the ith element of the collection.
void	removeListDataListener(ListDataListener l)
void	removePropertyChangeListener(PropertyChangeListener l)
void	removePropertyChangeListener(String propertyName, PropertyChangeListener l)
Object	set(int i, Object o)
protected boolean	shouldIncludeBeanColumn(PropertyDescriptor pd) Indicate whether a given introspected Bean property applicable to all the collection elements should be included in the columns of this Folder.
int	size() Get the number of elements in the collection.

Methods inherited from class java.util.AbstractList

add, addAll, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, removeRange, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

add, addAll, addAll, clear, contains, containsAll, equals, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, removeAll, retainAll, subList, toArray, toArray

Constructor Detail

CollectionFolder

public CollectionFolder(Object primaryObject)

Method Detail

get

public Object get(int i)

Get the i^th element, as defined by the primary object's natural ordering.

Specified by:

get in interface List

Overrides:

get in class AbstractList

Returns:

the appropriate object.

size

public int size()

Get the number of elements in the collection.

Specified by:

size in interface List

Overrides:

size in class AbstractCollection

Returns:

the number of elements.

set

public Object set(int i,
                  Object o)

Specified by:

set in interface List

Overrides:

set in class AbstractList

Throws:

UnsupportedOperationException - always.

add

public void add(int i,
                Object o)

Specified by:

add in interface List

Overrides:

add in class AbstractList

Throws:

UnsupportedOperationException - always.

remove

public Object remove(int i)

Remove the i^th element of the collection.

Specified by:

remove in interface List

Overrides:

remove in class AbstractList

Returns:

the value previously at this location.

Throws:

UnsupportedOperationException - if the primary object returns false from Collection.remove(Object).

getPrimaryObject

public Object getPrimaryObject()

Description copied from interface: Facet

Obtain the primary object of this Facet. The primary object is that object of which this Facet is an alternative representation. The primary object may or may not know that it is being represented by this Facet.

Specified by:

getPrimaryObject in interface Facet

Following copied from interface: org.favabeans.base.Facet

Returns:

the primary object.

getFacet

public Facet getFacet(Type type)

Description copied from interface: Faceted

Obtain a Facet of the requested Type for this object.

Specified by:

getFacet in interface Faceted

Following copied from interface: org.favabeans.base.Faceted

Parameters:

type - the Type of Facet requested for this object.

Returns:

a Facet, or null if none can be created as requested.

getColumns

public Column[] getColumns()

Description copied from interface: Folder

The columns of this Folder, represented as a set of Column objects.

Specified by:

getColumns in interface Folder

addListDataListener

public void addListDataListener(ListDataListener l)

Specified by:

addListDataListener in interface Folder

removeListDataListener

public void removeListDataListener(ListDataListener l)

Specified by:

removeListDataListener in interface Folder

isOrderingSemantic

public boolean isOrderingSemantic()

Description copied from interface: Folder

Determine whether the ordering of this Folder is merely coincidental, based on the need to make up an ordering for the convenience of UI elements, or semantic, that is to say, of actual importance to the underlying domain object model.

UI elements will typically only display "move up/down", "add before", "add after" and "add between" interactors to the end-user if this method returns true.

An example of a coincidental ordering is the ordering we would generate for files in a typical operating system directory. Though we can sort the files (see Column.getAscendingSort()), it does not make sense to add a new file "before" or "after" another one, or "between" two other files.

An example of a semantic ordering is what we would generate for a list of print jobs in a print queue, where the order of execution is based on the order of submission. An end-user with sufficient privileges may wish to move jobs forwards or backwards in the queue, or insert a new job at a specific position. @return true if the ordering is semantic; false otherwise.

Specified by:

isOrderingSemantic in interface Folder

isMutable

public boolean isMutable()

Description copied from interface: Folder

Determine whether this Folder supports mutation.

Specified by:

isMutable in interface Folder

Following copied from interface: org.favabeans.base.Folder

Returns:

true if elements can be added to or removed from this Folder.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)

Specified by:

addPropertyChangeListener in interface Folder

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)

Specified by:

removePropertyChangeListener in interface Folder

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener l)

Specified by:

addPropertyChangeListener in interface Folder

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener l)

Specified by:

removePropertyChangeListener in interface Folder

shouldIncludeBeanColumn

protected boolean shouldIncludeBeanColumn(PropertyDescriptor pd)

Indicate whether a given introspected Bean property applicable to all the collection elements should be included in the columns of this Folder.

This method is for the convenience of subclasses. The default implementation of this method always returns true.

Parameters:

pd - the Bean property descriptor for the given property.

Returns:

true if the property should be included; false otherwise.

buildAdditionalColumns

protected Column[] buildAdditionalColumns()

Build and return a set of additional Column objects which are not obtainable via Bean introspection.

This method is for the convenience of subclasses. The default implementation of this method returns an empty array.

Returns:

the additional Column objects.

getCollection

protected Collection getCollection()

fireStateChanged

protected void fireStateChanged()

fireContentsChanged

protected void fireContentsChanged()