source: trunk/src/org/apollo/audio/structure/AudioStructureModel.java@ 1434

package org.apollo.audio.structure;

import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Queue;
import java.util.Set;
import java.util.Stack;

import javax.sound.sampled.UnsupportedAudioFileException;

import org.apollo.audio.ApolloSubjectChangedEvent;
import org.apollo.io.AudioIO;
import org.apollo.mvc.AbstractSubject;
import org.apollo.mvc.SubjectChangedEvent;
import org.apollo.util.ExpediteeFileTextSearch;
import org.apollo.util.Mutable;
import org.apollo.util.TextItemSearchResult;
import org.apollo.widgets.LinkedTrack;
import org.apollo.widgets.SampledTrack;
import org.apollo.widgets.TrackWidgetCommons;
import org.expeditee.core.BlockingRunnable;
import org.expeditee.gio.EcosystemManager;
import org.expeditee.gui.DisplayController;
import org.expeditee.gui.Frame;
import org.expeditee.gui.FrameIO;
import org.expeditee.gui.management.ResourceManager;
import org.expeditee.io.Conversion;
import org.expeditee.items.ItemUtils;
import org.expeditee.items.widgets.Widget;
import org.expeditee.settings.folders.FolderSettings;

/**
 * A thread safe model of the hierarchical structure of a track graph...
 * abstracted from Expeditee frames and audio widgets.
 * 
 * The track widgets notify this model for keeping the structure consistent with
 * Expeditee's data.
 * 
 * 
 * <b>Thread safe convention:</b>
 * OverdubbedFrame's and TrackGraphInfo are always handled on the swing thread.
 * This class provides asynch loading routines but that is purely for loading - not
 * handling!
 * 
 * The track graph is a loop-free directed graph.
 * 
 * A graph root is a graph of OverdubbedFrame's
 * 
 * Although a {@link TrackGraphNode} or a {@link LinkedTracksGraphNode} may reside
 * in multiple graphs, there is always only one instance of them - they
 * are just shared.
 * 
 * There are multiple graphs because Graphs can be mutually exlusive.
 * Or some frames cannot be reached unless they are a starting point (aka root)
 * 
 * @author Brook Novak
 *
 */
public class AudioStructureModel extends AbstractSubject {
        
        /** 
         * A loop-free directed graph. 
         * For each graph root, there can be no other graph root that is
         * reachable (other than itself).
         */
        private Set<OverdubbedFrame> graphRoots = new HashSet<OverdubbedFrame>(); // SHARED RESOURCE
        
        /** All overdubbed frames loaded in memory. MAP = Framename -> Overdub instance */
        private Map<String, OverdubbedFrame> allOverdubbedFrames = new HashMap<String, OverdubbedFrame>(); // SHARED RESOURCE
        
        /** For resources {@link AudioStructureModel#graphRoots} and {@link AudioStructureModel#allOverdubbedFrames} */
        private Object sharedResourceLocker = new Object();
        
        private boolean cancelFetch = false;
        
        private DelayedModelUpdator delayedModelUpdator = null;

        private static AudioStructureModel instance = new AudioStructureModel();
        
        private AudioStructureModel() { }
        
        public static AudioStructureModel getInstance() {
                return instance;
        }
        
        /**
         * <b>MUST NOT BE IN THE EXPEDITEE THREAD! OTHERWISE WILL DEFINITELY DEADLOCK</b>
         * 
         * Same as {@link #fetchGraph(String)} but waits for any updates to finish before
         * the fetch.
         * 
         * Intention: really to highlight the need to call waitOnUpdates prior to this ... but
         * may not bee neccessary...
         * 
         * @param rootFrameName
         *              refer to #fetchGraph(String)
         * @return 
         *              refer to #fetchGraph(String)
         * 
         * @throws NullPointerException
         *              if rootFrameName is null.
         * 
         * @throws IllegalArgumentException
         *              If rootFrameName is not a valid framename.
         * 
         * @throws InterruptedException
         *              refer to #fetchGraph(String)
         * 
         * @throws TrackGraphLoopException
         *              refer to #fetchGraph(String) - 
         *              <B>However</B> - it could also be that the reason was due to the thread being interupted while
         *              waiting on a update to finish. Thus may want to manually wait for updates prior - see
         *              {@link #waitOnUpdates()}.
         * 
         * @see #fetchGraph(String)
         */
        public synchronized OverdubbedFrame fetchLatestGraph(String rootFrameName) 
                throws InterruptedException, TrackGraphLoopException {
                waitOnUpdates();
                return fetchGraph(rootFrameName);
        }
        
        /**
         * May have to read from file if not yet loaded in memory.
         * Thus it could take some time.
         * 
         * Thread safe.
         * 
         * NOTE: The intention is that this is called on a dedicated thread... other than
         * swings thread. However once a OverdubbedFrame is returned be sure
         * to only use it on the swing thread by convention. 
         * 
         * <b>MUST NOT NE IN THE EXPEDITEE THREAD! OTHERWISE WILL DEFINITELY DEADLOCK</b>
         * 
         * @param rootFrameName
         *              Must not be null. Mustn't be a link - must be the <i>framename</i>
         * 
         * @return
         *              The overdubbed frame.
         *              Null if the frame does not exist - or if it does exist but there
         *              are no track / linked-track widgets on it. Not that it can return
         *              a overdubbed frame that contains a heirarchy of linked overdubbed frames
         *      but no actual playable tracks.
         * 
         * @throws NullPointerException
         *              if rootFrameName is null.
         * 
         * @throws IllegalArgumentException
         *              If rootFrameName is not a valid framename.
         * 
         * @throws InterruptedException
         *              If the fetch request was cancelled because the model
         *              has changed in some way during the read. Must retry the fetch.
         * 
         * @throws TrackGraphLoopException
         *              If the requested root introduces loops to the current graph state.
         *              The loop trace will be provided in the exception. 
         * 
         * @see TrackGraphLoopException#getFullLoopTrace()
         * 
         */
        public synchronized OverdubbedFrame fetchGraph(String rootFrameName) 
                throws InterruptedException, TrackGraphLoopException {
                
                if(rootFrameName == null) throw new NullPointerException("rootFrameName");
                if(!FrameIO.isValidFrameName(rootFrameName))
                        throw new IllegalArgumentException("the rootFrameName \"" 
                                        + rootFrameName +"\" is not a valid framename");
                
                // reset flag
                cancelFetch = false; // note that race conditions here is beside the point...meaningless
                
                OverdubbedFrame rootODFrame = null;
                synchronized(sharedResourceLocker) {
                        rootODFrame = allOverdubbedFrames.get(rootFrameName.toLowerCase()); 
                }
                
                if (rootODFrame != null) {
                        return rootODFrame;
                }
                
                // There is no overdub frame loaded for the requested frame.
                // Thus create a new root
                Map<String, OverdubbedFrame> newGraph = new HashMap<String, OverdubbedFrame> ();
                rootODFrame = buildGraph(rootFrameName, newGraph); // throws InterruptedException's

                // There exists no such frame or is not an actual overdubbed frame
                if (rootODFrame == null || rootODFrame.isEmpty()) return null;
                
                // Must run on swing thread for checking for loops before commiting the new graph to 
                // the model.
                NewGraphCommitor commit = new NewGraphCommitor(rootODFrame, newGraph);
                try {
                        EcosystemManager.getMiscManager().runOnGIOThread(commit);
                } catch (Exception e) {
                        e.printStackTrace();
                        assert(false);
                }
                
                // Check if commit aborted
                if (commit.abortedCommit) {
                        
                        if (cancelFetch) { // Due to cancel request?
                                throw new InterruptedException();
                        } 
                        
                        // Must be due to loop
                        assert (!commit.loopTrace.isEmpty());
                        throw new TrackGraphLoopException(commit.loopTrace);
                }
                
                return rootODFrame;
        }
        
        /**
         * Assumption: that this is called from another thread other than the swing thread.
         * 
         * @param rootFrameName
         * 
         * @param newNodes
         * 
         * @return
         *              Null if rootFrameName does not exist
         * 
         * @throws InterruptedException
         */
        private OverdubbedFrame buildGraph(String rootFrameName, Map<String, OverdubbedFrame> newNodes)
                throws InterruptedException
        {
                // Must be a frame name, not a link
                assert(rootFrameName != null);
                assert(FrameIO.isValidFrameName(rootFrameName));
                
                // If cancelled the immediatly abort fetch
                if (cancelFetch) { // check for cancel request
                        throw new InterruptedException();
                }

                // Look for existing node on previously loaded graph...
                OverdubbedFrame oframe = null;
                synchronized(sharedResourceLocker) {
                        oframe = allOverdubbedFrames.get(rootFrameName.toLowerCase());
                }
        
                // Check to see if not already created this node during this recursive call
                if (oframe == null)
                        oframe = newNodes.get(rootFrameName.toLowerCase());

            if (oframe != null) return oframe; 

                // There are no existing nodes ... thus create a new node from searching for
                // the frame from file
                
                // But first .. look in expeditee's cache since the cache might not be consistent with the file system yet
                // .. or in the common case - the root could be the current frame.
                ExpediteeCachedTrackInfoFetcher cacheFetch = new ExpediteeCachedTrackInfoFetcher(rootFrameName);
                
                try {
                        EcosystemManager.getMiscManager().runOnGIOThread(cacheFetch);
                } catch (Exception e) {
                        e.printStackTrace();
                        assert(false);
                }
                
                /* Localfilename -> TrackModelData. */
                Map<String, TrackModelData> tracks = null;

                /* VirtualFilename -> LinkedTrackModelData. */
                Map<String, LinkedTrackModelData> linkedTracks = null;

                if (cacheFetch.tracks != null) {
                        
                        tracks = cacheFetch.tracks;
                        assert(cacheFetch.linkedTracks != null);
                        linkedTracks = cacheFetch.linkedTracks;
                        
                } else { // search on file system
                
                        String trackPrefix = ItemUtils.GetTag(ItemUtils.TAG_IWIDGET) + ": ";
                        String linkedTrackPrefix = trackPrefix;
                        
                        trackPrefix += SampledTrack.class.getName();
                        linkedTrackPrefix += LinkedTrack.class.getName();

                        String fullPath = null;
                        List<String> possiblePaths = FolderSettings.FrameDirs.getAbsoluteDirs();
                        
                        for (int i = 0; i < possiblePaths.size(); i++) { // RISKY CODE - IN EXPEDITEE SPACE FROM RANDOM TRHEAD
                                String possiblePath = possiblePaths.get(i);
                                fullPath = FrameIO.getFrameFullPathName(possiblePath, rootFrameName);
                                if (fullPath != null)
                                        break;
                        }
                        
                        // does even exist?
                        if (fullPath == null) {
                                return null;
                        }
                        
                        try {
                                
                                // Perform prefix search
                                List<TextItemSearchResult> results = ExpediteeFileTextSearch.prefixSearch(
                                                fullPath, 
                                                new String[] {trackPrefix, linkedTrackPrefix});
                                
                                // Parse search results
                                tracks = new HashMap<String, TrackModelData>();
                                linkedTracks = new HashMap<String, LinkedTrackModelData>();
                                
                                for (TextItemSearchResult result : results) {
                                
                                        // Track widget
                                        if (result.text.startsWith(trackPrefix)) {
                                                
                                                String name = null;
                                                String localFileName = null;
                                                Mutable.Long initiationTime = null;
                                                
                                                for (String data : result.data) { // read data lines
                                                        data = data.trim();
                                                        
                                                        if (data.startsWith(SampledTrack.META_LOCALNAME_TAG) &&
                                                                        data.length() > SampledTrack.META_LOCALNAME_TAG.length()) {
                                                                localFileName = data.substring(SampledTrack.META_LOCALNAME_TAG.length());
                                                        
                                                        } else if (data.startsWith(TrackWidgetCommons.META_INITIATIONTIME_TAG) 
                                                                        && data.length() > TrackWidgetCommons.META_INITIATIONTIME_TAG.length()) {
                                                                
                                                                try {
                                                                        initiationTime = Mutable.createMutableLong(Long.parseLong(
                                                                                        data.substring(TrackWidgetCommons.META_INITIATIONTIME_TAG.length())));
                                                                } catch (NumberFormatException e) { /* Consume */ }
                                                        
                                                        } else if (data.startsWith(TrackWidgetCommons.META_NAME_TAG) 
                                                                        && data.length() > TrackWidgetCommons.META_NAME_TAG.length()) {
                                                                
                                                                name = data.substring(TrackWidgetCommons.META_NAME_TAG.length());
                                                        
                                                        }
                                                }
                                                
                                                // Add track to map
                                                if (localFileName != null) {
                                                        tracks.put(localFileName, new TrackModelData(
                                                                        initiationTime, -1, name, result.position.getY())); // pass -1 for running time to signify that must be read from audio file
                                                }
                                                
                                        // Linked track widget
                                        } else {
                                                
                                                assert(result.text.startsWith(linkedTrackPrefix));
                        
                                                // If the linked track infact has a link
                                                if (result.explink != null && result.explink.length() > 0) {
                                                
                                                        Mutable.Long initiationTime = null;
                                                        String virtualFilename = null;
                                                        String name = null;
                                                        
                                                        for (String data : result.data) { // read data lines
                                                                data = data.trim();
                                                                
                                                                // OK OK, Smell in code here - duplicated from above. - sorta
                                                                if (data.startsWith(LinkedTrack.META_VIRTUALNAME_TAG) &&
                                                                                data.length() > LinkedTrack.META_VIRTUALNAME_TAG.length()) {
                                                                        virtualFilename = data.substring(LinkedTrack.META_VIRTUALNAME_TAG.length());
                                                                
                                                                } else if (data.startsWith(TrackWidgetCommons.META_INITIATIONTIME_TAG) 
                                                                                && data.length() > TrackWidgetCommons.META_INITIATIONTIME_TAG.length()) {
                                                                        
                                                                        try {
                                                                                initiationTime = Mutable.createMutableLong(Long.parseLong(
                                                                                                data.substring(TrackWidgetCommons.META_INITIATIONTIME_TAG.length())));
                                                                        } catch (NumberFormatException e) { /* Consume */ }
                                                                
                                                                } else if (data.startsWith(TrackWidgetCommons.META_NAME_TAG) 
                                                                                && data.length() > TrackWidgetCommons.META_NAME_TAG.length()) {
                                                                        
                                                                        name = data.substring(TrackWidgetCommons.META_NAME_TAG.length());
                                                                
                                                                }
                                                        }
                                                        
                                                        // Add linked track to map
                                                        if (virtualFilename != null) {
                                                                linkedTracks.put(virtualFilename, new LinkedTrackModelData(
                                                                                initiationTime, result.explink, name, result.position.getY())); // pass -1 for running time to signify that must be read from audio file
                                                        }
                                                
                                                }
                                                
                
                                        }
                                        
                                } // Proccess next result
                                
                        } catch (FileNotFoundException e) {
                                e.printStackTrace();
                                return null;
                        } catch (IOException e) {
                                e.printStackTrace();
                                return null;
                        }

                }
                
                if (cancelFetch) { // check for cancel request
                        throw new InterruptedException();
                }
                
                assert(tracks != null);
                assert(linkedTracks != null);
                
                // Add new node (avoid infite recursion)
                oframe = new OverdubbedFrame(rootFrameName);
                newNodes.put(rootFrameName.toLowerCase(), oframe);
                
                // Load track times from file
                for (String localFilename : tracks.keySet()) {
                        
                        if (cancelFetch) { // check for cancel request
                                throw new InterruptedException();
                        }
                        
                        TrackModelData tmodel = tracks.get(localFilename);
                        if (tmodel.runningTimeMS <= 0) {
                                try {
                                        
                                        String localFilePath = ResourceManager.getAudioResource(localFilename, DisplayController.getCurrentFrame()).getAbsolutePath();
                                        tmodel.runningTimeMS = AudioIO.getRunningTime(localFilePath);
                                
                                } catch (IOException e) {
                                        e.printStackTrace();
                                } catch (UnsupportedAudioFileException e) {
                                        e.printStackTrace();
                                }
                        }
                        
                        // If was able to get the runnning time ... then include in model
                        if (tmodel.runningTimeMS > 0) {
                                
                                if (tmodel.initiationTime == null) {
                                        tmodel.initiationTime = Mutable.createMutableLong(oframe.getFirstInitiationTime());
                                        // Remember: initiation times are relative, so setting to zero
                                        // could be obscure.
                                }
                                
                                oframe.addTrack(new TrackGraphNode(
                                                tmodel.initiationTime.value,
                                                localFilename, 
                                                tmodel.runningTimeMS,
                                                tmodel.name,
                                                tmodel.ypos));

                        } // otheriwse omit from model.
                        
                }
                
                // Get linked OverdubbedFrame's.. recurse
                for (String virtualFilename : linkedTracks.keySet()) {
                        
                        LinkedTrackModelData linkedTrackModel = linkedTracks.get(virtualFilename);
                        
                        // At this point, the link may / maynot be absolute,
                        String linkedFrameName = linkedTrackModel.frameLink;
                        assert(linkedFrameName != null);
                        
                        if (linkedFrameName.length() == 0) continue;
                        
                        if (!(Character.isLetter(linkedFrameName.charAt(0)))) { // relative link
                                // Heres a trick: to get the frameset of the relative link - its just the
                                // current root framenames frameset
                                linkedFrameName = Conversion.getFramesetName(rootFrameName) + linkedFrameName; // WARNING: IN EXPEDITEE THREAD
                        }

                        OverdubbedFrame od = buildGraph(linkedFrameName, newNodes); // Recurse
                        
                        if (od == null) { // bad link or empty frame
                                od = new OverdubbedFrame(linkedFrameName);
                        }
                        
                        if (linkedTrackModel.initiationTime == null) {
                                linkedTrackModel.initiationTime = Mutable.createMutableLong(oframe.getFirstInitiationTime());
                                // Remember: initiation times are relative, so setting to zero
                                // could be obscure.
                        }
                        
                        oframe.addLinkedTrack(new LinkedTracksGraphNode(
                                        linkedTrackModel.initiationTime.value, 
                                        od, 
                                        virtualFilename,
                                        linkedTrackModel.name,
                                        linkedTrackModel.ypos));
                        
                }
        
                return oframe;
        }
        
        /**
         * 
         * @author Brook Novak
         *
         */
        private class TrackModelData {
                
                TrackModelData(Mutable.Long initiationTime, long runningTimeMS, String name, int ypos) {
                        this.initiationTime = initiationTime;
                        this.runningTimeMS = runningTimeMS;
                        this.name = name;
                        this.ypos = ypos;
                }
                
                /** Null if unavilable */
                Mutable.Long initiationTime;
                
                /** negative if unavailable */
                long runningTimeMS; 
                
                /** Can be null. Trackname */
                String name;
                
                int ypos;
        }

        /**
         * 
         * @author Brook Novak
         *
         */
        private class LinkedTrackModelData {
                
                LinkedTrackModelData(Mutable.Long initiationTime, String frameLink, String name, int ypos) {
                        assert(frameLink != null);
                        this.initiationTime = initiationTime;
                        this.frameLink = frameLink;
                        this.name = name;
                        this.ypos = ypos;
                }
                /** Null if unavilable */
                Mutable.Long initiationTime;
                
                /** The framename */
                String frameLink;
                
                /** Can be null. Trackname */
                String name;
                
                /** The y pixel position */
                int ypos;
        }
        
        /**
         * Used for fetching track info in expeditees cache
         * 
         * @author Brook Novak
         *
         */
        private class ExpediteeCachedTrackInfoFetcher extends BlockingRunnable
        {
                private String rootFrameName;
                
                /** Localfilename -> TrackModelData. Not null if frame was in memory. */
                Map<String, TrackModelData> tracks = null;

                /** VirtualFilename -> LinkedTrackModelData. Not null if frame was in memory. */
                Map<String, LinkedTrackModelData> linkedTracks = null;

                ExpediteeCachedTrackInfoFetcher(String rootFrameName)
                {
                        assert(rootFrameName != null);
                        this.rootFrameName = rootFrameName;
                }
                
                public void execute()
                {
                        assert(rootFrameName != null);
                        
                        // Check if the current frame
                        Frame rootFrame = null;
                        if (DisplayController.getCurrentFrame() != null && DisplayController.getCurrentFrame().getName() != null
                                        && DisplayController.getCurrentFrame().getName().equals(rootFrameName)) {
                                rootFrame = DisplayController.getCurrentFrame();
                        } else {
                                // Check if in cache
                                rootFrame = FrameIO.FrameFromCache(rootFrameName);
                        }
                        
                        // Frame exists in memory... rummage around for track meta data
                        if (rootFrame != null) {
                                tracks = new HashMap<String, TrackModelData>();
                                linkedTracks =  new HashMap<String, LinkedTrackModelData>();
                                
                                for (Widget iw : rootFrame.getInteractiveWidgets()) {
                                        
                                        if (iw instanceof SampledTrack) {
                                                SampledTrack sampledTrackWidget = (SampledTrack)iw;

                                                TrackGraphNode tinf = 
                                                        AudioStructureModel.getInstance().getTrackGraphInfo(
                                                                        sampledTrackWidget.getLocalFileName(), 
                                                                        rootFrameName);
                                                
                                                Mutable.Long initTime = (tinf != null) ? Mutable.createMutableLong(tinf.getInitiationTime()) :
                                                        sampledTrackWidget.getInitiationTimeFromMeta();

                                                long runningTime = sampledTrackWidget.getRunningMSTimeFromRawAudio();
                                                if (runningTime <= 0) runningTime = -1; // signify to load from file
                                                
                                                tracks.put(sampledTrackWidget.getLocalFileName(), 
                                                                new TrackModelData(
                                                                                initTime,
                                                                                runningTime,
                                                                                sampledTrackWidget.getName(),
                                                                                sampledTrackWidget.getY()));
                                                
                                                // NOTE: If the audio was sotred in a recovery file - then the widget would
                                                // be deleted - thus no need to consider recovery files.
                                                
                                        } else if (iw instanceof LinkedTrack) {
                                                LinkedTrack linkedTrackWidget = (LinkedTrack)iw;
                        
                                                LinkedTracksGraphNode ltinf = 
                                                        AudioStructureModel.getInstance().getLinkedTrackGraphInfo(
                                                                        linkedTrackWidget.getVirtualFilename(), 
                                                                        rootFrameName);
                        
                                                Mutable.Long initTime = (ltinf != null) ? Mutable.createMutableLong(ltinf.getInitiationTime()) :
                                                        linkedTrackWidget.getInitiationTimeFromMeta();
                                
                                                // Don't consider track-links without any links
                                                if (linkedTrackWidget.getLink() != null) {
                                                        linkedTracks.put(linkedTrackWidget.getVirtualFilename(), 
                                                                        new LinkedTrackModelData(
                                                                                        initTime,
                                                                                        linkedTrackWidget.getLink(),
                                                                                        linkedTrackWidget.getName(),
                                                                                        linkedTrackWidget.getY()));
                                                }

                                        }
                                        
                                }
                                
                        }
                }
        }
        

        /**
         * Used for commiting a new graph in a thread-safe way.
         * Checks for loops in the graph before commiting.
         * 
         * If did not commit, then {@link #abortedCommit} will be true. Otherwise it will be false.
         * 
         * if {@link #loopTrace} is not empty after the run, then the commit
         * was aborted because there was a loop. (And {@link #loopTrace} contains the trace).
         * The only other reason for aborting the commit was if a cancel was requested 
         * (@see TrackGraphModel#cancelFetch)
         * 
         * @author Brook Novak
         * 
         *
         */
        private class NewGraphCommitor extends BlockingRunnable
        {
                private final OverdubbedFrame rootODFrame;
                private final Map<String, OverdubbedFrame> newGraph;
                
                private boolean abortedCommit = false;
                
                /** If not empty after the run, then the commit */
                Stack<OverdubbedFrame> loopTrace = new Stack<OverdubbedFrame>();

                NewGraphCommitor(OverdubbedFrame rootODFrame, Map<String, OverdubbedFrame> newGraph)
                {
                        assert(rootODFrame != null);
                        assert(newGraph != null);
                        
                        this.rootODFrame = rootODFrame;
                        this.newGraph = newGraph;
                }
                
                public void execute()
                {
                        
                        // Theoretically this would never need to be called ... but for super safety
                        // keep sync block - since dealing with shared resources.
                        synchronized(sharedResourceLocker) {
                                
                                // At anytime during this point, the new graph could become invalid
                                // during this time while officially adding it to the "consistant" model..
                                // which is obviously BAD.
                                if (cancelFetch) {
                                        abortedCommit = true;
                                        return; // important: while locked shared resources
                                }
                                
                                // Check that the graph is loop free.
                                boolean ilf = isLoopFree(rootODFrame, loopTrace);
                                if (ilf) { // check from existing roots POV's
                                        for (OverdubbedFrame existingRoot : graphRoots) {
                                                loopTrace.clear();
                                                ilf = isLoopFree(existingRoot, loopTrace);
                                                if (!ilf) break;
                                        }
                                }
                                
                                if (!ilf) {
                                        assert (!loopTrace.isEmpty()); // loopTrace will contain the trace
                                        abortedCommit = true;
                                        return;
                                } else {
                                        assert (loopTrace.isEmpty());
                                }
                                
                                // Since we are creating a new root, existing roots might
                                // be reachable from the new root, thus remove reachable
                                // roots ... since they are no longer roots ...
                                List<OverdubbedFrame> redundantRoots = new LinkedList<OverdubbedFrame>();
                                for (OverdubbedFrame existingRoot : graphRoots) {
                                        if (rootODFrame.getChild(existingRoot.getFrameName()) != null) {
                                                redundantRoots.add(existingRoot); // this root is reachable from the new root
                                        }
                                }
        
                                // Get rid of the redundant roots
                                graphRoots.removeAll(redundantRoots);
                                
                                // Commit the new loop-free graph to the model
                                graphRoots.add(rootODFrame); // add the mutex or superceeding root
                                allOverdubbedFrames.putAll(newGraph); // Include new graph into all allOverdubbedFrames
                        }
                }
        }
//      
//      /**
//       * Determines if a node is reachable from a given node.
//       * 
//       * @param source
//       *              Must not be null.
//       * 
//       * @param target
//       *              Must not be null.
//       * 
//       * @param visited
//       *              Must be empty. Must not be null.
//       * 
//       * @return
//       *                      True if target is reachable via source.
//       */
//      private boolean isReachable(OverdubbedFrame source, OverdubbedFrame target, Set<OverdubbedFrame> visited) {
//              assert(source != null);
//              assert(target != null);
//              assert(visited != null);
//              
//              // Base cases
//              if (source == target) return true;
//              else if (visited.contains(source)) return false;
//              
//              // Remember visited node
//              visited.add(source);
//              
//              // Recurse
//              for (Iterator<LinkedTracksGraphInfo> itor = source.getLinkedTrackIterator(); itor.hasNext();) {
//                      LinkedTracksGraphInfo lti = itor.next();
//                      
//                      if (isReachable(lti.getLinkedFrame(), target, visited)) {
//                              return true;
//                      }
//              }
//              
//              // Reached end of this nodes links - found no match
//              return false;
//      }

        /**
         * Determines if a graph is loop free from a starting point.
         * <B>MUST BE ON THE SWING THREAD</B>
         * 
         * @param current
         *              Where to look for loops from.   
         * 
         * @param visitedStack
         *              Must be empty. Used internally. If the
         *              function returns false, then the stack will provde a trace of the loop.
         * 
         * @return
         *              True if the graph at current is loop free.
         */
        private boolean isLoopFree(OverdubbedFrame current, Stack<OverdubbedFrame> visitedStack) {
                
                if (visitedStack.contains(current)) {  // found a loop
                        visitedStack.add(current); // add to strack for loop trace.
                        return false;
                }

                visitedStack.push(current); // save current node to stack

                for (LinkedTracksGraphNode tl : current.getLinkedTracksCopy()) {
                        
                        boolean ilf = isLoopFree(tl.getLinkedFrame(), visitedStack);
                        
                        if (!ilf) return false;
                        
                }
                
                visitedStack.pop(); // pop the current node
                
                return true;
                
        }
        
        /**
         * Gets a TrackGraphInfo. <b>MUST BE ON EXPEDITEE THREAD</b>
         * 
         * @param localFilename
         *                      Must not be null.
         * 
         * @param parentFrameName
         *                      If null - the search will be slower.
         * 
         * @return
         *              The TrackGraphInfo for the given track. Null if not in model
         */
        public TrackGraphNode getTrackGraphInfo(String localFilename, String parentFrameName) {
                
                synchronized(sharedResourceLocker) { 
                        
                        assert(localFilename != null);
                        
                        if (parentFrameName != null) {
                                OverdubbedFrame odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                                
                
                                if (odframe != null) { 
                                        return odframe.getTrack(localFilename);
                                }
                                
                        } else { // parentFrameName is null .. do search
                                
                                for (OverdubbedFrame odframe : allOverdubbedFrames.values()) {
                                        TrackGraphNode tinf = odframe.getTrack(localFilename);
                                        if (tinf != null) return tinf;
                                }
                        }
                }
                        
                return null;
        }
        

        /**
         * Gets a TrackGraphInfo. <b>MUST BE ON EXPEDITEE THREAD</b>
         * 
         * @param virtualFilename
         *                      Must not be null.
         * 
         * @param parentFrameName
         *                      If null - the search will be slower.
         * 
         * @return
         *              The LinkedTracksGraphInfo for the given virtualFilename. Null if not in model
         */
        public LinkedTracksGraphNode getLinkedTrackGraphInfo(String virtualFilename, String parentFrameName) {
                
                synchronized(sharedResourceLocker) { 
                        
                        assert(virtualFilename != null);
                        
                        if (parentFrameName != null) {
                                OverdubbedFrame odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                                
                
                                if (odframe != null) { 
                                        return odframe.getLinkedTrack(virtualFilename);
                                }
                                
                        } else {
                                
                                for (OverdubbedFrame odframe : allOverdubbedFrames.values()) {
                                        LinkedTracksGraphNode ltinf = odframe.getLinkedTrack(virtualFilename);
                                        if (ltinf != null) return ltinf;
                                }
                                
                        }
                }
                        
                return null;
        }
        
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Gets the parent ODFrame of a track - given the tracks local filename.
         * 
         * @param localFilename
         *              The local filename of the track to get the frame for. Must not be null.
         * 
         * @return
         *              The parent. Null if no parent exists.
         */
        public OverdubbedFrame getParentOverdubbedFrame(String localFilename) {
                assert(localFilename != null);
                
                synchronized (allOverdubbedFrames) {
                        for (OverdubbedFrame odf : allOverdubbedFrames.values()) {
                                if (odf.containsTrack(localFilename)) {
                                        return odf;
                                }
                        }
                }
                
                return null;
        }
        
        /**
         * Gets an overdubbed frame representation of a given frame.
         * 
         * @param framename
         *              The name of the frame.
         * 
         * @return
         *              The OverdubbedFrame for the given framename. Null if does not exist.
         */
        public OverdubbedFrame getOverdubbedFrame(String framename) {
                assert(framename != null);
                
                synchronized (allOverdubbedFrames) {
                        return allOverdubbedFrames.get(framename.toLowerCase());
                }
        }
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * @param localFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null.
         * 
         * @param currentRunningTime
         *              I.e. the new running time after the edit. Must be larger than zero. In milliseconds. 
         */
        public void onTrackWidgetAudioEdited(String localFilename, String parentFrameName, long currentRunningTime) {
                
                boolean doNotify = false;
                TrackGraphNode tinf = null;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources
                        
                        assert(localFilename != null);
                        assert (currentRunningTime > 0);

                        // Locate parent frame
                        OverdubbedFrame odframe = null;
                        
                        if (parentFrameName != null) odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                        else odframe = getParentOverdubbedFrame(localFilename);

                        // adjust running time in model
                        if (odframe != null) { // is loaded?
                                tinf = odframe.getTrack(localFilename);
                                assert(tinf != null); // due to the assumption that the model is consistent
                                if (tinf.getRunningTime() != currentRunningTime) {
                                        tinf.setRunningTime(currentRunningTime);
                                        // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                        // It will die in its own time - and will always be cancelled because it locks
                                        // the current locked object.
                                        cancelFetch = doNotify = true;
                                }
                        }

        
                }
                
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.GRAPH_TRACK_EDITED, tinf));
        }
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * @param localFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null.
         * 
         * @param newInitiationTime
         *              In milliseconds.Relative - i.e. can be negative
         * 
         * @param name
         *              The name given to the linked track. Can be null if there is no name...
         * 
         * @param ypos
         *              The Y-pixel position of the track.
         * 
         * @param currentRunningTime
         *              Must be larger than zero. In milliseconds. Used in case the model has not been create for the widget.
         */
        public void onTrackWidgetAnchored(
                        String localFilename, String parentFrameName, 
                        long newInitiationTime, long currentRunningTime,
                        String name, int ypos) {
                
                boolean doNotify = false;
                TrackGraphNode tinf = null;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources
                        
                        assert(localFilename != null);

                        // Locate parent frame
                        OverdubbedFrame odframe = null;
                        
                        if (parentFrameName != null) odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                        else odframe = getParentOverdubbedFrame(localFilename);
                        
                        // adjust initiation time in model
                        if (odframe != null) { // is loaded?
                                tinf = odframe.getTrack(localFilename);
                                
                                if (tinf != null && tinf.getInitiationTime() != newInitiationTime) {
                                        tinf.setInitiationTime(newInitiationTime);
                                        cancelFetch = doNotify = true;
                                        
                                } else { // if there is no model but overdub frame is in memory - then create new model for this track.
                                        
                                        tinf = new TrackGraphNode(
                                                        newInitiationTime, 
                                                        localFilename, 
                                                        currentRunningTime,
                                                        name,
                                                        ypos);
                                        
                                        odframe.addTrack(tinf); // safe because on swing thread 
                                        
                                        // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                        cancelFetch = doNotify = true;
                                        // It will die in its own time - and will always be cancelled because it locks
                                        // the current locked object.
                                }
                                

                        }

                }
                
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.GRAPH_TRACK_ADDED, tinf));
                
        }
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * Note: Invoke when picked up - not when a frame changes... also if it
         * is removed due to XRaymode - in that case the whole model will be released.
         * 
         * @param localFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null. If given will be faster.
         * 
         */
        public void onTrackWidgetRemoved(String localFilename, String parentFrameName) {
                TrackGraphNode tinf = null;
                boolean doNotify = false;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources

                        if (DisplayController.isXRayMode()) { // discard whole model

                                // Neccessary because if the user goes into xray then moves to a new frame
                                // then it wil screw everything up. Also note they can delete the text source items
                                // in xray mode.
                                // This basically will cause short load times to occur again...
                                allOverdubbedFrames.clear();
                                graphRoots.clear();

                                // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                cancelFetch = doNotify = true;
                                // It will die in its own time - and will always be cancelled because it locks
                                // the current locked object.
                                
                        } else {
                                
                                // Locate parent frame
                                OverdubbedFrame odframe = null;
                                
                                if (parentFrameName != null) odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                                else odframe = getParentOverdubbedFrame(localFilename);
                                
                                if (odframe != null) {
                                        tinf = odframe.removeTrack(localFilename);
                                        //assert(tinf != null);
                                        cancelFetch = doNotify = true;
                                }
                                
                        }

                }
                        
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.GRAPH_TRACK_REMOVED, tinf));
        }
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * @param localFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null.
         * 
         * @param currentRunningTime
         *              I.e. the new running time after the edit. Must be larger than zero. In milliseconds. 
         */
        public void onTrackWidgetNameChanged(String localFilename, String parentFrameName, String newName) {

                boolean doNotify = false;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources
                        
                        assert(localFilename != null);

                        // Locate parent frame
                        OverdubbedFrame odframe = null;
                        
                        if (parentFrameName != null) odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                        else odframe = getParentOverdubbedFrame(localFilename);
                        
                        // adjust name in model
                        if (odframe != null) { // is loaded?
                                AbstractTrackGraphNode tinf = odframe.getTrack(localFilename);
                                assert(tinf != null); // due to the assumption that the model is consistent
                                if (tinf.getName() != newName) {
                                        tinf.setName(newName);
                                        // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                        cancelFetch = doNotify = true;
                                        // It will die in its own time - and will always be cancelled because it locks
                                        // the current locked object.
                                } 
                        }

                }
                
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.NAME_CHANGED, localFilename));
        }
        
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * @param localFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null.
         * 
         * @param initTime
         *              The initiation time in ms
         * 
         * @param yPos
         *              The y pixel position.
         * 
         */
        public void onTrackWidgetPositionChanged(String localFilename, String parentFrameName, long initTime, int yPos) {

                boolean doNotify = false;
                AbstractTrackGraphNode tinf = null;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources
                        
                        assert(localFilename != null);

                        // Locate parent frame
                        OverdubbedFrame odframe = null;

                        if (parentFrameName != null) odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                        else odframe = getParentOverdubbedFrame(localFilename);
                        
                        // adjust name in model
                        if (odframe != null) { // is loaded?
                                tinf = odframe.getTrack(localFilename);
                                if (tinf != null && 
                                                (tinf.getInitiationTime() != initTime || tinf.getYPixelPosition() != yPos)) {
                                        tinf.setInitiationTime(initTime);
                                        tinf.setYPixelPosition(yPos);
                                        // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                        cancelFetch = doNotify = true;
                                        // It will die in its own time - and will always be cancelled because it locks
                                        // the current locked object.
                                } 
                        }

                }
                
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.GRAPH_TRACK_POSITION_CHANGED, tinf));
        }


        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * @param virtualFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null.
         * 
         * @param initTime
         *              The initiation time in ms
         * 
         * @param yPos
         *              The y pixel position.
         * 
         */
        public void onLinkedTrackWidgetPositionChanged(String virtualFilename, String parentFrameName, long initTime, int yPos) {

                boolean doNotify = false;
                AbstractTrackGraphNode tinf = null;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources
                        
                        assert(virtualFilename != null);

                        // Locate parent frame
                        OverdubbedFrame odframe = null;
                        
                        if (parentFrameName != null) odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                        else odframe = getParentOverdubbedFrame(virtualFilename);
                        
                        // adjust name in model
                        if (odframe != null) { // is loaded?
                                tinf = odframe.getLinkedTrack(virtualFilename);
                                if (tinf != null && 
                                                (tinf.getInitiationTime() != initTime || tinf.getYPixelPosition() != yPos)) {
                                        
                                        tinf.setInitiationTime(initTime);
                                        tinf.setYPixelPosition(yPos);
                                        
                                        // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                        cancelFetch = doNotify = true;
                                        // It will die in its own time - and will always be cancelled because it locks
                                        // the current locked object.
                                } 
                        }
                }
                
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.GRAPH_LINKED_TRACK_POSITION_CHANGED, tinf));
        }
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * @param virtualFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null.
         * 
         * @param currentRunningTime
         *              I.e. the new running time after the edit. Must be larger than zero. In milliseconds. 
         */
        public void onLinkedTrackWidgetNameChanged(String virtualFilename, String parentFrameName, String newName) {

                boolean doNotify = false;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources
                        
                        assert(virtualFilename != null);

                        // Locate parent frame
                        OverdubbedFrame odframe = null;
                        
                        if (parentFrameName != null) odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                        else odframe = getParentOverdubbedFrame(virtualFilename);
                        
                        // adjust name in model
                        if (odframe != null) { // is loaded?
                                AbstractTrackGraphNode tinf = odframe.getLinkedTrack(virtualFilename);
                                if (tinf != null && tinf.getName() != newName) {
                                        tinf.setName(newName);
                                        // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                        cancelFetch = doNotify = true;
                                        // It will die in its own time - and will always be cancelled because it locks
                                        // the current locked object.
                                } 
                        }
                }
                
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.NAME_CHANGED, virtualFilename));
        }
        
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * Doe not use for changing a the widgets link. Must first remove, then acnhor with new link - 
         * tracklinks links are immutable.
         * 
         * @param virtualFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Must not be null.
         * 
         * @param newInitiationTime
         *              In milliseconds.Relative - i.e. can be negative
         * 
         * @param absoluteLinkedFrame
         *              Must not be null. Must be a valid framename (absolute).
         * 
         * @param name
         *              The name given to the linked track. Can be null if there is no name...
         * 
         * @param ypos
         *              The Y-pixel position of the track.
         * 
         */
        public void onLinkedTrackWidgetAnchored(
                        String virtualFilename, String parentFrameName, 
                        long newInitiationTime, String absoluteLinkedFrame,
                        String name, int ypos) {
                
                boolean doNotify = false;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources
                        
                        assert(virtualFilename != null);
                        assert(parentFrameName != null);
                        assert(absoluteLinkedFrame != null);
                        assert(FrameIO.isValidFrameName(absoluteLinkedFrame));
                        
                        // Locate parent frame
                        OverdubbedFrame odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                        
                        if (odframe != null) { // is loaded?
                                
                                LinkedTracksGraphNode linkInf = odframe.getLinkedTrack(virtualFilename);

                                if (linkInf != null) {
                                        
                                        // Update the initation time
                                        linkInf.setInitiationTime(newInitiationTime);
                                        
                                        // The link should be consistant - check for miss-use of procedure call
                                        assert(linkInf.getLinkedFrame().getFrameName().equalsIgnoreCase(absoluteLinkedFrame));
                                                                                
                                } else { // if there is no model but overdub frame is in memory - then create new model for this track.
                                        
                                        updateLater(new LinkedTrackUpdate(
                                                        newInitiationTime, absoluteLinkedFrame,
                                                        virtualFilename, parentFrameName, name, ypos));
                                        
                                }
                                
                                // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                cancelFetch = doNotify = true;
                                // It will die in its own time - and will always be cancelled because it locks
                                // the current locked object.
                        }

                }
                
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.GRAPH_LINKED_TRACK_ADDED, virtualFilename));
                
        }
        
        /**
         * <B>MUST BE ON SWING THREAD</B>.
         * Keeps model consistent with expeditee.
         * 
         * Note: Invoke when picked up - not when a frame changes... also if it
         * is removed due to XRaymode - in that case the whole model will be released.
         * 
         * <b>Also</b> invoke if the track tracks link has changed.
         * 
         * @param virtualFilename
         *              Must not be null.
         * 
         * @param parentFrameName
         *              Can be null. If given will be faster.
         * 
         */
        public void onLinkedTrackWidgetRemoved(String virtualFilename, String parentFrameName) {
                
                boolean doNotify = false;
                
                synchronized(sharedResourceLocker) { // IMPORTANT: Must wait for new graphs to be added to the shared resources

        
                        if (DisplayController.isXRayMode()) { // discard whole model

                                // Neccessary because if the user goes into xray then moves to a new frame
                                // then it wil screw everything up. Also note they can delete the text source items
                                // in xray mode.
                                // This basically will cause short load times to occur again...
                                allOverdubbedFrames.clear();
                                graphRoots.clear();
                                
                                
                                // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                cancelFetch = doNotify = true;
                                // It will die in its own time - and will always be cancelled because it locks
                                // the current locked object.
                        } else {
                                
                                // Locate parent frame
                                OverdubbedFrame odframe = null;
                                
                                if (parentFrameName != null) {
                                        odframe = allOverdubbedFrames.get(parentFrameName.toLowerCase());
                                } else { 
                                        for (OverdubbedFrame odf : allOverdubbedFrames.values()) {
                                                if (odf.containsLinkedTrack(virtualFilename)) {
                                                        odframe = odf;
                                                        break;
                                                }
                                        }
                                }
                                
                                if (odframe != null) {
                                        LinkedTracksGraphNode linkInf = odframe.getLinkedTrack(virtualFilename);
                                        
                                        if (linkInf != null) {
                                                boolean didRemove = odframe.removeLinkedTrack(linkInf);
                                                assert(didRemove);
                                                
                                                // Track links are the actual links in the directed graph. THus if they are
                                                // removed then the graph must be checked for creating new root nodes.
                                                // That is, the removed link may have isolated a node (or group of nodes)
                                                // for which must be reachable via their own start state...
                                                boolean isReachable = false;
                                                for (OverdubbedFrame existingRoot : graphRoots) {
                                                        if (existingRoot.getChild(linkInf.getLinkedFrame().getFrameName()) != null) {
                                                                isReachable = true;
                                                                break;
                                                        }
                                                        
                                                }
                                                
                                                // Ensure that the frame is reachable
                                                if (!isReachable) {
                                                        graphRoots.add(linkInf.getLinkedFrame());
                                                }
                                                
                                                // Note: a fetch might be waiting on this - i.e in progress. Thus must be cancelled.
                                                cancelFetch = doNotify = true;
                                                // It will die in its own time - and will always be cancelled because it locks
                                                // the current locked object.
                                        
                                        }
                                        
                                        
                                }
                                
                        }
                
                }
                        
                // Notify observers.
                if (doNotify)
                        fireSubjectChanged(new SubjectChangedEvent(ApolloSubjectChangedEvent.GRAPH_LINKED_TRACK_REMOVED, virtualFilename));
        }
        
        /**
         * @return
         *                      True if the graph model is updating.
         */
        public boolean isUpdating() {
                return (delayedModelUpdator != null && delayedModelUpdator.isAlive());
        }

        
        /**
         * Waits for updates to finish.
         * 
         * <b>MUST NOT BE ON SWING THREAD - OR MAY DEADLOCK</b>
         * 
         * @throws InterruptedException
         *              if any thread has interrupted the current thread
         */
        public void waitOnUpdates() throws InterruptedException {
                if (delayedModelUpdator != null && delayedModelUpdator.isAlive()) {
                        delayedModelUpdator.join();
                }
        }
        
        /**
         * Queues an update for the consistant model to be updated later... since it may take some time.
         * 
         * @param update
         *              The update to do. Must not be null.
         */
        private void updateLater(LinkedTrackUpdate update) {
                
                synchronized(updateQueue) {
                        
                        assert(update != null);

                        // Add the update tot he queu
                        updateQueue.add(update);
                
                        // Ensure that the update thread is alive
                        if (delayedModelUpdator == null || !delayedModelUpdator.isAlive()) {
                                delayedModelUpdator = new DelayedModelUpdator();
                                delayedModelUpdator.start();
                        }
                        
                }       
                        
        }

        private Queue<LinkedTrackUpdate> updateQueue = new LinkedList<LinkedTrackUpdate>(); // SHARED RESOURCE
        
        /**
         * Used for queuing update data.
         * 
         * 
         * @author Brook Novak
         *
         */
        private class LinkedTrackUpdate extends LinkedTrackModelData {
                
                LinkedTrackUpdate(
                                long initiationTime, 
                                String absoluteLink, 
                                String virtualFilename, 
                                String parentFrameToAddTo,
                                String name,
                                int ypos) {
                        
                        super(Mutable.createMutableLong(initiationTime), absoluteLink, name, ypos);
                        
                        assert(virtualFilename != null);
                        assert(parentFrameToAddTo != null);
                        assert(FrameIO.isValidFrameName(absoluteLink));
                        
                        this.virtualFilename = virtualFilename;
                        this.parentFrameToAddTo = parentFrameToAddTo;
                }
                
                String virtualFilename;
                String parentFrameToAddTo;
                
        }
        
        /**
         * 
         * @author Brook Novak
         *
         */
        private class DelayedModelUpdator extends Thread {
                
                public void run() {
                        while (true) {
                                LinkedTrackUpdate update;
                                synchronized(updateQueue) {
                                        if (updateQueue.isEmpty()) return; // important: only quits when updateQueue is synched
                                        update = updateQueue.poll();
                                }
                                
                                assert(update != null);
                                
                                // Keep trying the update until success or encountered loops
                                while (true) {
                                        try {
                                                
                                                OverdubbedFrame odframe = fetchGraph(update.frameLink);
                                                if (odframe == null) { // does not exist or is empty...
                                                        odframe = new OverdubbedFrame(update.frameLink);
                                                }
                                                

                                                // add to parent only if does not already exist - also being aware of loops
                                                final LinkedTrackUpdate updateData = update;
                                                final OverdubbedFrame linkedODFrame = odframe;
                                                
                                                try {
                                                        EcosystemManager.getMiscManager().runOnGIOThread(new BlockingRunnable() {
                                                                
                                                                public void execute() { // on swing thread

                                                                        synchronized(sharedResourceLocker) {
                                                                                
                                                                                try { // The fetch will be cancelled after this block - within the lock
                                                                                                                                        
                                                                                        OverdubbedFrame parentFrame = allOverdubbedFrames.get(updateData.parentFrameToAddTo.toLowerCase());
                                                                                        if (parentFrame == null) {
                                                                                                // No need to both adding - because model does not even reference this new link...
                                                                                                // must have cleared while updating... e.g. user could have switched into xray mode.
                                                                                                return;
                                                                                        }
                                                                                        
                                                                                        assert(updateData.initiationTime != null);
                                                                                        
                                                                                        // Create the linked track instance
                                                                                        LinkedTracksGraphNode linktInf = new LinkedTracksGraphNode(
                                                                                                        updateData.initiationTime.value, 
                                                                                                        linkedODFrame, 
                                                                                                        updateData.virtualFilename,
                                                                                                        updateData.name,
                                                                                                        updateData.ypos);

                                                                                        // Check that the graph will be loop free
                                                                                        parentFrame.addLinkedTrack(linktInf); // ADDING TEMPORARILY

                                                                                        // Check from parent frame
                                                                                        Stack<OverdubbedFrame> loopTrace = new Stack<OverdubbedFrame>();
                                                                                        if (!isLoopFree(parentFrame, loopTrace)) {
                                                                                                parentFrame.removeLinkedTrack(linktInf);
                                                                                                // Ignore link - has loop
                                                                                                return;
                                                                                        }
                                                                                        
                                                                                        // Check for all existing graph roots
                                                                                        for (OverdubbedFrame existingRoot : graphRoots) {
                                                                                                loopTrace.clear();
                                                                                                if (!isLoopFree(existingRoot, loopTrace)) {
                                                                                                        parentFrame.removeLinkedTrack(linktInf);
                                                                                                        // Ignore link - has loop
                                                                                                         return;
                                                                                                }
                                                                                        }
                        
                                                                                        // Otherwise leave the link in its place 
                                                                                        
                                                                                        // Ensure that the linked frame is in the allOverdubbedFrames set
                                                                                        allOverdubbedFrames.put(linkedODFrame.getFrameName().toLowerCase(), linkedODFrame);
                                                                                
                                                                                } finally { // IMPORTANT: CANCEL WHILE LOCKED
                                                                                        
                                                                                        // Cancel any fetches
                                                                                        cancelFetch = true;
                                                                                }       
                                                                                
                                                                        }  // release lock
                                                                
                                                                                
                                                                }
                                                        });
                                                } catch (Exception e) {
                                                        e.printStackTrace();
                                                        assert(false);
                                                }
                
                                                // Done with this update...
                                                break;
                                                
                                                
                                        } catch (InterruptedException e) { // Canceled
                                                // Consume and retry
                                                
                                        } catch (TrackGraphLoopException e) { // bad link
                                                // Consume - since is fine - the model will just ignore the link
                                                break;
                                        }
                                } // retry fetch
                                
                        } // proccess next update
                        
                } // finished updating
        }
        
}