Package org.biojava.utils

Class ChangeSupport

  • public class ChangeSupport
extends 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), Kalle Naslund (tiny bugfix)

    • 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​(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