com.sas.collection
Class BaseCollection

com.sas.collection.BaseCollection

All Implemented Interfaces:

com.sas.beans.PropertyChangeSource, com.sas.beans.VetoableChangeSource, com.sas.collection.ContentsChangedSource, StaticCollectionInterface, ComponentInterface, LinkPropertiesInterface, ModelInterface, com.sas.PublicClonable, com.sas.util.Countable, com.sas.util.Enumerable, com.sas.util.EventGateInterface, ViewInterface, MultipleValueEventSourceInterface, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.lang.Cloneable, java.util.EventListener

Direct Known Subclasses:

AssociationList, Collection, CollectionMirror, Dictionary, OrderedCollection, OrderedListCollection, SortedCollection, StringCollection

public abstract class BaseCollection
implements StaticCollectionInterface, java.io.Serializable, com.sas.util.EventGateInterface, com.sas.PublicClonable

Abstract base class for collections. This class provides some default implementation for some of the collections.

See Also:

Serialized Form

Field Summary

protected com.sas.collection.ContentsChangedListenerList	allContentsChangedListeners allContentsChangedListeners is a list of listeners for the ContentsChangedEvent event.
protected static java.lang.Object	mappingObject A replacement for null for internally used JDK collections (Hashtable) which do not handle null.

Constructor Summary

BaseCollection()

Method Summary

void	addContentsChangedListener(com.sas.collection.ContentsChangedListener listener) Add a listener for the com.sas.collection.ContentsChangedEvent event.
protected boolean	anyContentsChangedListeners() Test is there are any registered event listeners for a ContentsChangedEvent, or any registered listeners for a PropertyChangeEvent.
void	apply(com.sas.util.ApplyInterface action) Applies an action to every item in the collection.
java.lang.Object	clone() Clone the object.
boolean	contains(java.lang.Object element) Test for the presence of an object in this collection.
abstract int	count() Returns the number of items in this collection
void	disableEvents() Ask this collection to suppress delivery of ContentsChangeEvents on subsequent changes to this collection.
void	enableEvents() Undo a disableEvents() call.
void	enableEvents(com.sas.collection.ContentsChangedEvent event) Undo a disableEvents() call.
protected void	fireContentsChanged(com.sas.collection.ContentsChangedEvent event) Send a ContentsChangedEvent event to all the ContentsChangedListener objects in the listener list.
abstract java.util.Enumeration	getItems() Return an enumeration of all the elements in this collection
protected static java.lang.Object	map(java.lang.Object o) Substitute the mappingObject for null object references.
void	removeContentsChangedListener(com.sas.collection.ContentsChangedListener listener) Remove a listener for the com.sas.collection.ContentsChangedEvent event.
protected static java.lang.Object	unmap(java.lang.Object o) The inverse of the map(Object) call.

Methods inherited from class com.sas.Component

addLink, addPropertyChangeListener, addVetoableChangeListener, anyPropertyChangeListeners, attachModel, attachView, beansIsDesignTime, beansSetDesignTime, clone, detachModel, detachView, dumpComponent, firePropertyChange, firePropertyChange, fireVetoableChange, getComponentDescription, getComponentSupportInfo, getEventMethod, getEventValues, getExtendedBeanInfo, getLinkInfo, getModelInterface, getRequiredInterfaces, getResources, getStringResource, getViewInterfaceSupportInfo, initialize, initializeComponent, isDesignTime, isLinked, propertyChange, queryLinks, queryLinks, refresh, removeAllLinks, removeInterfaceTraps, removeLink, removePropertyChangeListener, removeVetoableChangeListener, setComponentDescription, setComponentSupportInfo, setDefaultValues, setLinkInfo, setModelInterface, setRequiredInterfaces, setViewInterfaceSupportInfo, supportsListenerInterface, supportsRequiredInterfaces, trapInterfaceEvents, validateObject

Methods inherited from interface com.sas.beans.PropertyChangeSource

addPropertyChangeListener, removePropertyChangeListener

Field Detail

mappingObject

protected static final java.lang.Object mappingObject

A replacement for null for internally used JDK collections (Hashtable) which do not handle null.

See Also:

map(Object), unmap(Object)

allContentsChangedListeners

protected transient com.sas.collection.ContentsChangedListenerList allContentsChangedListeners

allContentsChangedListeners is a list of listeners for the ContentsChangedEvent event.

See Also:

addContentsChangedListener(com.sas.collection.ContentsChangedListener), removeContentsChangedListener(com.sas.collection.ContentsChangedListener), anyContentsChangedListeners()

Constructor Detail

BaseCollection

public BaseCollection()

Method Detail

count

public abstract int count()

Returns the number of items in this collection

Specified by:

count in interface com.sas.util.Countable

Returns:

the number of items in this collection

getItems

public abstract java.util.Enumeration getItems()

Return an enumeration of all the elements in this collection

Specified by:

getItems in interface com.sas.util.Enumerable

Returns:

an enumeration of the items. If the specific collection does not support enumerations, the getItems() method returns null. An empty collection still returns an Enumeration, but the first call to hasMoreElements() returns false.

See Also:

Enumerable.getItems()

contains

public boolean contains(java.lang.Object element)

Test for the presence of an object in this collection. This base implementation is based on scanning an enumeration; concrete subclasses may have more efficient implementations.

Specified by:

contains in interface StaticCollectionInterface

Parameters:

element - The item to search for

Returns:

true if and only if the item exists in this collection

Throws:

java.lang.ClassCastException - In some implementations, the objects that are stored may be restricted to a particular type (such as String).

See Also:

StaticCollectionInterface.contains(java.lang.Object)

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clone the object.

Specified by:

clone in interface StaticCollectionInterface

Specified by:

clone in interface com.sas.PublicClonable

Overrides:

clone in class Component

Returns:

a clone of this collection.

Throws:

java.lang.CloneNotSupportedException - if the clone fails.

apply

public void apply(com.sas.util.ApplyInterface action)

Applies an action to every item in the collection. This is a general way to modify all the items in a collection. This does not replace the collection elements.

Subclasses may have a more efficient implementation.

Specified by:

apply in interface StaticCollectionInterface

Parameters:

action - An object performs some action on another object. action.apply(item) is excecuted on successive items in this collection until all items have been operated on, or until the method returns ApplyInterface.ABORT

map

protected static java.lang.Object map(java.lang.Object o)

Substitute the mappingObject for null object references. Implementation classes which use other objects that do not handle null references should use map(Object) to change null references to a fixed non-null reference (BaseCollection.mappingObject) before storing items in the underlying object. For example, Dictionary uses a Hashtable which does not allow null keys, so Dictionary runs all keys through map(key). The mapped value can then be translated back to null via the unmap(Object) method.

Parameters:

o - an object.

Returns:

mappingObject if o == null, else o

See Also:

unmap(java.lang.Object), mappingObject

unmap

protected static java.lang.Object unmap(java.lang.Object o)

The inverse of the map(Object) call.

Parameters:

o - an object in a collection (possibly the mappingObject )

Returns:

null if o is the mappingObject, else the object o

See Also:

mappingObject, map(Object)

addContentsChangedListener

public void addContentsChangedListener(com.sas.collection.ContentsChangedListener listener)

Add a listener for the com.sas.collection.ContentsChangedEvent event.

Specified by:

addContentsChangedListener in interface com.sas.collection.ContentsChangedSource

Parameters:

listener - an object which handles ContentsChangedEvent events. The listener is not added a second time if it already exists in the list of listeners for this event. If listener is null, it is ignored.

See Also:

ContentsChangedSource

removeContentsChangedListener

public void removeContentsChangedListener(com.sas.collection.ContentsChangedListener listener)

Remove a listener for the com.sas.collection.ContentsChangedEvent event. Nothing happens if the listener is not in the list of listeners for this event.

Specified by:

removeContentsChangedListener in interface com.sas.collection.ContentsChangedSource

Parameters:

listener - an object which handles ContentsChangedEvent events

See Also:

ContentsChangedSource

fireContentsChanged

protected void fireContentsChanged(com.sas.collection.ContentsChangedEvent event)

Send a ContentsChangedEvent event to all the ContentsChangedListener objects in the listener list. The event is sent only to each item which is in the list at the time this method is called, even if adds or removes are performed after the this method has started. Also sends the event, which extends PropertyChangeEvent, to all registered property change listeners.

Parameters:

event - the event to send

anyContentsChangedListeners

protected boolean anyContentsChangedListeners()

Test is there are any registered event listeners for a ContentsChangedEvent, or any registered listeners for a PropertyChangeEvent.

Returns:

true if there is one or more listeners for either a ContentsChangedEvent or a PropertyChangeEvent. Returns false if events are disabled.

See Also:

disableEvents(), enableEvents()

disableEvents

public void disableEvents()

Ask this collection to suppress delivery of ContentsChangeEvents on subsequent changes to this collection.

This call should always appear in a try { } block, with the matching enableEvents() method in the finally { } block.

Specified by:

disableEvents in interface com.sas.util.EventGateInterface

See Also:

enableEvents(), anyContentsChangedListeners()

enableEvents

public void enableEvents()

Undo a disableEvents() call. This may or may not cause the collection to start sending events again. If there are no other pending suppress/allow gates on this collection, this collection will send a single ContentsChangedEvent and then subsequent changes to this collection will also fire ContentsChangedEvents.

This call should always appear in a finally { } block; the disableEvents() calls should be in the try { } block.

Specified by:

enableEvents in interface com.sas.util.EventGateInterface

See Also:

disableEvents(), anyContentsChangedListeners()

enableEvents

public void enableEvents(com.sas.collection.ContentsChangedEvent event)

Undo a disableEvents() call. This may or may not cause the collection to start sending events again. If there are no other pending suppress/allow gates on this collection, this collection will send the specified event (unless it is null) and then subsequent changes to this collection will also fire ContentsChangedEvents.

This call should always appear in a finally block; the disableEvents calls should be in the try block.

Parameters:

event - an event to fire to the listeners if there are other no pending enableEvents methods. If null, do not fire any event. This is useful if a concrete class wishes to fire a more specific event.