org.biojava.utils
Class ChangeSupport

java.lang.Object
  extended byorg.biojava.utils.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
Author:
Matthew Pocock, Thomas Down, Keith James (docs)

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)
           
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)
 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()
           
 boolean isUnchanging(ChangeType ct)
           
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)

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()

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.

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.

Parameters:
ce - the ChangeEvent to pass on

isUnchanging

public boolean isUnchanging(ChangeType ct)