org.jscience.util
Class ChangeSupport

java.lang.Object
  org.jscience.util.ChangeSupport

public class ChangeSupport
extends java.lang.Object

A utility class to provide management for informing ChangeListeners of ChangeEvents.

This is loosely modelled after the standard PropertyChangeEvent objects.

For an object to correctly fire these events, they must follow a broad outline like this:

 public void mutator(foo arg) throw ChangeVetoException {
   ChangeEvent cevt = new ChangeEvent(this, SOME_EVENT_TYPE, arg);
   synchronized(changeSupport) {
     changeSupport.firePreChangeEvent(cevt);
     // update our state using arg
     // ...
     changeSupport.firePostChangeEvent(cevt);
   }
 }
 

The methods that delegate adding and removing listeners to a ChangeSupport must take responsibility for synchronizing on the delegate.

Since:

1.1

Constructor Summary

ChangeSupport()
Generate a new ChangeSupport instance.

ChangeSupport(int initialSize)
Generate a new ChangeSupport instance which has room for initialSize listeners before it needs to grow any resources.

ChangeSupport(int initialSize, int delta)
Generate a new ChangeSupport instance which has room for initialSize listeners before it needs to grow any resources, and which will grow by delta each time.

ChangeSupport(java.util.Set unchanging)
Creates a new ChangeSupport object.

ChangeSupport(java.util.Set unchanging, int initialSize, int delta)
Generate a new ChangeSupport instance which has room for initialSize listeners before it needs to grow any resources, and which will grow by delta each time.

Method Summary

void	addChangeListener(ChangeListener cl) Add a listener that will be informed of all changes.
void	addChangeListener(ChangeListener cl, ChangeType ct) Add a listener that will be informed of changes of a given type (and it's subtypes)
java.lang.String	displayString() DOCUMENT ME!
void	firePostChangeEvent(ChangeEvent ce) Inform the listeners that a change has taken place using their firePostChangeEvent methods.
void	firePreChangeEvent(ChangeEvent ce) Inform the listeners that a change is about to take place using their firePreChangeEvent methods.
protected void	growIfNecessary() Grows the internal resources if by adding one more listener they would be full.
boolean	hasListeners() Return true if we have any listeners registered at all.
boolean	hasListeners(ChangeType ct) Return true if we have listeners registered for a particular change type.
boolean	isUnchanging(ChangeType ct) DOCUMENT ME!
protected void	reapGarbageListeners() Remove all references to listeners which have been cleared by the garbage collector.
void	removeChangeListener(ChangeListener cl) Remove a listener that was interested in all types of changes.
void	removeChangeListener(ChangeListener cl, ChangeType ct) Remove a listener that was interested in a specific types of changes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ChangeSupport

public ChangeSupport()

Generate a new ChangeSupport instance.

ChangeSupport

public ChangeSupport(int initialSize)

Generate a new ChangeSupport instance which has room for initialSize listeners before it needs to grow any resources.

Parameters:

initialSize - the number of listeners that can be added before this needs to grow for the first time

ChangeSupport

public ChangeSupport(int initialSize,
                     int delta)

Generate a new ChangeSupport instance which has room for initialSize listeners before it needs to grow any resources, and which will grow by delta each time.

Parameters:

initialSize - the number of listeners that can be added before this needs to grow for the first time

delta - the number of listener slots that this will grow by each time it needs to

ChangeSupport

public ChangeSupport(java.util.Set unchanging)

Creates a new ChangeSupport object.

Parameters:

unchanging - DOCUMENT ME!

ChangeSupport

public ChangeSupport(java.util.Set unchanging,
                     int initialSize,
                     int delta)

Generate a new ChangeSupport instance which has room for initialSize listeners before it needs to grow any resources, and which will grow by delta each time.

Parameters:

unchanging - Set of ChangeTypes that can never be fired

initialSize - the number of listeners that can be added before this needs to grow for the first time

delta - the number of listener slots that this will grow by each time it needs to

Method Detail

hasListeners

public boolean hasListeners()

Return true if we have any listeners registered at all.

Returns:

true if there are listeners

hasListeners

public boolean hasListeners(ChangeType ct)

Return true if we have listeners registered for a particular change type.

Parameters:

ct - the ChangeType to check

Returns:

true if there are listeners for this type

addChangeListener

public void addChangeListener(ChangeListener cl)

Add a listener that will be informed of all changes.

Parameters:

cl - the ChangeListener to add

addChangeListener

public void addChangeListener(ChangeListener cl,
                              ChangeType ct)

Add a listener that will be informed of changes of a given type (and it's subtypes)

Parameters:

cl - the ChangeListener

ct - the ChangeType it is to be informed of

growIfNecessary

protected void growIfNecessary()

Grows the internal resources if by adding one more listener they would be full.

removeChangeListener

public void removeChangeListener(ChangeListener cl)

Remove a listener that was interested in all types of changes.

Parameters:

cl - a ChangeListener to remove

removeChangeListener

public void removeChangeListener(ChangeListener cl,
                                 ChangeType ct)

Remove a listener that was interested in a specific types of changes.

Parameters:

cl - a ChangeListener to remove

ct - the ChangeType that it was interested in

reapGarbageListeners

protected void reapGarbageListeners()

Remove all references to listeners which have been cleared by the garbage collector. This method should only be called when the object is locked.

firePreChangeEvent

public void firePreChangeEvent(ChangeEvent ce)
                        throws ChangeVetoException

Inform the listeners that a change is about to take place using their firePreChangeEvent methods.

Listeners will be informed if they were interested in all types of event, or if ce.getType() is equal to the type they are registered for.

This method must be called while the current thread holds the lock on this change support.

Parameters:

ce - the ChangeEvent to pass on

Throws:

ChangeVetoException - if any of the listeners veto this change

firePostChangeEvent

public void firePostChangeEvent(ChangeEvent ce)

Inform the listeners that a change has taken place using their firePostChangeEvent methods.

Listeners will be informed if they were interested in all types of event, or if ce.getType() is equal to the type they are registered for.

This method must be called while the current thread holds the lock on this change support.

Parameters:

ce - the ChangeEvent to pass on

isUnchanging

public boolean isUnchanging(ChangeType ct)

DOCUMENT ME!

Parameters:

ct - DOCUMENT ME!

Returns:

DOCUMENT ME!

displayString

public java.lang.String displayString()

DOCUMENT ME!

Returns:

DOCUMENT ME!