/*
 * Copyright (c) 2007-2010 The Regents of the University of California.
 * All rights reserved.
 *
 * '$Author: crawl $'
 * '$Date: 2018-02-07 18:20:17 +0000 (Wed, 07 Feb 2018) $' 
 * '$Revision: 34660 $'
 * 
 * Permission is hereby granted, without written agreement and without
 * license or royalty fees, to use, copy, modify, and distribute this
 * software and its documentation for any purpose, provided that the above
 * copyright notice and the following two paragraphs appear in all copies
 * of this software.
 *
 * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
 * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
 * THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
 * PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
 * CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
 * ENHANCEMENTS, OR MODIFICATIONS.
 *
 */

package org.kepler.provenance;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Writer;
import java.lang.ref.WeakReference;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Hashtable;
import java.util.Iterator;
import java.util.LinkedHashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
import java.util.WeakHashMap;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.kepler.configuration.ConfigurationManager;
import org.kepler.configuration.ConfigurationProperty;
import org.kepler.configuration.ConfigurationUtilities;
import org.kepler.objectmanager.lsid.KeplerLSID;
import org.kepler.objectmanager.lsid.LSIDGenerator;
import org.kepler.provenance.sql.SQLRecordingParameters;
import org.kepler.sms.SemanticType;
import org.kepler.ssh.SshEvent;
import org.kepler.ssh.SshEventListener;
import org.kepler.ssh.SshEventRegistry;
import org.kepler.tagging.TagEvent;
import org.kepler.tagging.TagEventListener;
import org.kepler.util.WorkflowRenameListener;
import org.kepler.util.WorkflowRenameManager;
import org.kepler.util.WorkflowRun;

import ptolemy.actor.Actor;
import ptolemy.actor.ActorFiringListener;
import ptolemy.actor.CompositeActor;
import ptolemy.actor.Director;
import ptolemy.actor.Executable;
import ptolemy.actor.ExecutionListener;
import ptolemy.actor.FiringEvent;
import ptolemy.actor.FiringsRecordable;
import ptolemy.actor.IOPort;
import ptolemy.actor.IOPortEvent;
import ptolemy.actor.IOPortEventListener;
import ptolemy.actor.IORelation;
import ptolemy.actor.Initializable;
import ptolemy.actor.Manager;
import ptolemy.actor.TypedIOPort;
import ptolemy.actor.gui.ColorAttribute;
import ptolemy.actor.gui.Effigy;
import ptolemy.actor.gui.SizeAttribute;
import ptolemy.actor.gui.WindowPropertiesAttribute;
import ptolemy.actor.lib.hoc.CaseDirector;
import ptolemy.actor.lib.hoc.IterateOverArray;
import ptolemy.actor.lib.hoc.MultiInstanceComposite;
import ptolemy.actor.parameters.PortParameter;
import ptolemy.actor.parameters.SharedParameter;
import ptolemy.data.BooleanToken;
import ptolemy.data.StringToken;
import ptolemy.data.Token;
import ptolemy.data.expr.ExpertParameter;
import ptolemy.data.expr.Parameter;
import ptolemy.data.expr.StringParameter;
import ptolemy.data.expr.Variable;
import ptolemy.data.type.BaseType;
import ptolemy.domains.ddf.kernel.DDFDirector;
import ptolemy.domains.de.kernel.DEDirector;
import ptolemy.domains.pn.kernel.PNDirector;
import ptolemy.domains.sdf.kernel.SDFDirector;
import ptolemy.kernel.CompositeEntity;
import ptolemy.kernel.Entity;
import ptolemy.kernel.Relation;
import ptolemy.kernel.util.Attribute;
import ptolemy.kernel.util.ChangeListener;
import ptolemy.kernel.util.ChangeRequest;
import ptolemy.kernel.util.DebugEvent;
import ptolemy.kernel.util.DebugListener;
import ptolemy.kernel.util.Debuggable;
import ptolemy.kernel.util.IllegalActionException;
import ptolemy.kernel.util.KernelException;
import ptolemy.kernel.util.NameDuplicationException;
import ptolemy.kernel.util.Nameable;
import ptolemy.kernel.util.NamedObj;
import ptolemy.kernel.util.Settable;
import ptolemy.kernel.util.ValueListener;
import ptolemy.kernel.util.Workspace;
import ptolemy.moml.MoMLChangeRequest;
import ptolemy.util.MessageHandler;
import ptolemy.vergil.basic.KeplerDocumentationAttribute;
import ptolemy.vergil.kernel.attributes.TextAttribute;

/** A listener that records workflow provenance information. It implements
 *  several Kepler and Ptolemy listener interfaces in order to receive
 *  events for workflow specification, and execution. Provenance data
 *  is stored using a particular <code>Recording</code> implementation.
 *
 * @author Daniel Crawl
 * @version $Id: ProvenanceRecorder.java 34660 2018-02-07 18:20:17Z crawl $
 * @see Recording
 *
 */
public class ProvenanceRecorder extends Attribute implements ExecutionListener, 
    ChangeListener, IOPortEventListener, ActorFiringListener, DebugListener,
    ValueListener, SshEventListener, Initializable, WorkflowRenameListener, 
    TagEventListener
{       
    /** Construct a provenance recorder in the default workspace using the
     *  TOP Recorder Name specified in the configuration file.
     *  NOTE: to use the provenance recorder for recording, you must set the
     *  container.
     *  
     *  NOTE: this constructor can be used for certain recording events that
     *  don't refer to the container.
     */
    public ProvenanceRecorder() 
        throws IllegalActionException, NameDuplicationException 
    {
        super();
        _setDefaultName();
        _init();
    }
    
    /**
     *  Construct a provenance recorder in the default workspace using
     *  non-default ConfigurationProperty.
     *
     * @param configProperty
     * @throws IllegalActionException
     * @throws NameDuplicationException
     */
    public ProvenanceRecorder(ConfigurationProperty configProperty) 
        throws IllegalActionException, NameDuplicationException 
    {
        super();
        _settingsProperty = configProperty;
        _setDefaultName();
        _init();
    }
            
    /** Construct a provenance recorder using the specified container.
     *  The name is set from the TOP Recorder Name specified in the
     *  configuration file.
     * @param container the container of the provenance recorder.
     */
    public ProvenanceRecorder(CompositeEntity container)
        throws IllegalActionException, NameDuplicationException
    {
        this(container, "");
        _setDefaultName();
    }

    /** Construct a provenance recorder in the workspace with an empty name.
     *  The listener is added to the list of objects in the workspace.
     *  Increment the version number of the workspace.
     *
     *  @param workspace The workspace for this object.
     */
    public ProvenanceRecorder(Workspace workspace) 
        throws IllegalActionException, NameDuplicationException 
    {
        super(workspace);
        _init();
    }

    /** Construct a provenance recorder in the given container with the 
     *  given name. The container argument must not be null, or a 
     *  NullPointerException will be thrown. If the name argument is null,
     *  then the name is set to the empty string. Increment the version 
     *  number of the workspace.
     *
     *  @param container Container of the director.
     *  @param name Name of this listener.
     *  @exception IllegalActionException If the listener is not compatible
     *   with the specified container.  May be thrown in a derived class.
     *  @exception NameDuplicationException If the container is not a
     *   CompositeActor and the name collides with an entity in the container.
     */
        public ProvenanceRecorder(CompositeEntity container, String name)
        throws IllegalActionException, NameDuplicationException 
    {       
        super(container, name);
        _init();
    }
   
    ///////////////////////////////////////////////////////////////////
    ////                         parameters                        ////

    /** If true, delay recording specification as long as possible. */
    public Parameter delayRecordingSpecification;

    /** Which Recording to use. */
    public StringParameter recordingType = null;

    /** Record system data on ssh'd machines. */
    //public Parameter recordSshData = null;

    /** Record token values. */
    public Parameter recordTokens = null;

    /** Local hostname. */
    public StringParameter hostname;

    /** Username. */
    public StringParameter username;
    
    /** String used when disabling provenance recording */
    public final static String DEFAULT_REC_TYPE_IGNORE = "Ignore";
    
    /** The LSID of the containing workflow. */
    public StringParameter containerWorkflowLSID;
    
    /** The name of the containing workflow. */
    public StringParameter containerWorkflowName;

    ///////////////////////////////////////////////////////////////////
    ////                         public methods                    ////

    /** React to attribute change (of ProvenanceRecorder only).
     * 
     *  @param attribute The attribute that changed.
     *  @exception IllegalActionException If the function is not recognized.
     */
    @Override
    public void attributeChanged(Attribute attribute) 
        throws IllegalActionException 
    {
        //System.out.println("att changed: " + attribute.getFullName());

        if(attribute == recordingType)
        {
            Recording oldRecording = _provStore;

            _changeRecordingType();

            // see if this is the first time the recording type was set
            if(oldRecording == null && _provStore != null)
            {
                // for all of the unknown attributes that were changed
                // earlier that belong to the recording, tell the recording
                // that they have changed.
                for(Attribute possibleAtt : _possibleRecordingAttributes) 
                {
                    //if(_provStoreParams.containsParameter(possibleAtt))
                    //{
                        _provStore.attributeChanged(possibleAtt);
                    //}
                }
                _possibleRecordingAttributes.clear();
            }
        }
        else if(attribute == recordTokens)
        {
            Token token = recordTokens.getToken();
            _recordTokensVal = ((BooleanToken)token).booleanValue();
        }
        else if(attribute == delayRecordingSpecification)
        {
            Token token = delayRecordingSpecification.getToken();
            _delayRecordingSpecificationVal =
                ((BooleanToken)token).booleanValue();
        }
        else if(attribute == containerWorkflowLSID)
        {
            String lsidStr = containerWorkflowLSID.stringValue();
            if(lsidStr.length() > 0 && _provStore != null)
            {
                try
                {
                    KeplerLSID lsid = new KeplerLSID(lsidStr);
                    _provStore.setContainerLSID(lsid);
                }
                catch(Exception e)
                {
                    throw new IllegalActionException(this, e, "Error creating KeplerLSID");
                }
            }
        }
        else if(attribute == containerWorkflowName)
        {
            String name = containerWorkflowName.stringValue();
            if(_provStore != null)
            {
                _provStore.setContainerName(name);
            }
        }
        /* not implemented
        else if(attribute == recordSshData)
        {
            Token token = recordSshData.getToken();
            _recordSshDataVal = ((BooleanToken)token).booleanValue();

            if(_recordSshDataVal)
            {
                throw new IllegalActionException(this, 
                    "Recording ssh system data not implemented.");
            }
        }
        */
        // see if attribute is from recording type
        /*
        else if(_provStoreParams != null &&
            _provStoreParams.containsParameter(attribute))
        {
            _provStore.attributeChanged(attribute);
        }
        */
        else
        {
            super.attributeChanged(attribute);

            // the attribute may belong to the recording; store so
            // that when the recording type is set, we can notify it
            // of any of its changed values.
            if(_provStore == null)
            {
                _possibleRecordingAttributes.add(attribute);
            }
            else
            {
                //System.out.println("sending possible attribute: " +
                    //attribute.getName());
                _provStore.attributeChanged(attribute);
            }
        }
    }

    /** Clone the ProvenanceRecorder into a specified workspace. */
    @Override
    public Object clone(Workspace workspace) throws CloneNotSupportedException {
        
        // do not clone the recording
        Recording provStore = _provStore;
        _provStore = null;
        ProvenanceRecorder newObject = (ProvenanceRecorder) super.clone(workspace);
        _provStore = provStore;
        
        try {
            newObject._init();
        } catch (IllegalActionException | NameDuplicationException e) {
            throw new CloneNotSupportedException(
                    "Error initializing ProvenanceRecorder: " + e.getMessage());
        }
        return newObject;
    }
    
    /** Change the container. If previously in a container, stop listening.
     *  If put into a new container, start listening to that container.
     */
    @Override
    public void setContainer(NamedObj container)
        throws IllegalActionException, NameDuplicationException
    {

        NamedObj oldContainer = getContainer();
        
        // see if the name is set
        if(getName().length() == 0)
        {
            // NOTE: the model may already contain an object with an empty
            // name, so set the name to the default value.
            // the KAR in http://bugzilla.ecoinformatics.org/show_bug.cgi?id=5197
            // contains objects with empty names.
            
            _setDefaultName();
        }

        super.setContainer(container);

        if(container == null)
        {
            //_Debug("set container to null");
        }
        else
        {
            //_Debug("set container to " + container.getFullName() + " hash " + container.hashCode());
            //_Debug("  my hash = " + hashCode());
        }

        // see if we changed containers
        if(container != oldContainer)
        {
            // if we had a previous container, stop listening to that one
            if(oldContainer != null && (oldContainer instanceof CompositeActor))
            {
                ((CompositeActor)oldContainer).removeInitializable(this);

                // stop listening to all events.
                _stopListening();

                // see if we were removed from model
                if(container == null)
                {
                    _removedFromModel = true;

                    Manager manager = 
                        ((CompositeActor)oldContainer).getManager();
                    if(manager != null)
                    {
                        manager.removeExecutionListener(this);
                    }
                    _addedExecutionListener = false;

                    disconnect();                    
                }
            }
            else // we were added to model
            {
                SshEventRegistry.instance.addListener(this);
                WorkflowRenameManager wrm = WorkflowRenameManager.getInstance();
                                wrm.addRenameListener(this);
            }

            // see if we were not removed from model
            if(container != null)
            {
                if(container instanceof CompositeActor)
                {
                    ((CompositeActor)container).addInitializable(this);
                    // NOTE: we do not call _addChangeEventSender() since
                    // changeEventSenders is null and we cannot create
                    // it since we are being called from our parent's
                    // constructor.
                    container.addChangeListener(this);
                }

                _haveExecuted = false;
            }
        }
            
        // notify the recording if present.
        if(_provStore != null)
        {
            _provStore.setContainer(this);
            
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.setContainer(this);
            }
        }
    }
    
    /** Perform cleanup. */
    public void disconnect() throws IllegalActionException
    {
        SshEventRegistry.instance.removeListener(this);

        if(_provStore != null)
        {
            try
            {
                _provStore.disconnect();

                // notify any piggybacks
                for(Recording recording : _piggybacks)
                {
                    recording.disconnect();
                }
            }
            catch(RecordingException e)
            {
                throw new IllegalActionException(this, e,
                    "Error disconnecting recording.");
            }
        }

        WorkflowRenameManager wrm = WorkflowRenameManager.getInstance();
        wrm.removeRenameListener(this);
    }

    /** Perform cleanup for all ProvenanceRecorder instances. */
    public static void disconnectAll() throws IllegalActionException
    {
        for(WeakReference<ProvenanceRecorder> reference : _recorders)
        {
            ProvenanceRecorder recorder = reference.get();
            if(recorder != null)
            {
                recorder.disconnect();
            }
        }
    }

    /** Return true if provenance output is turned on. */
    public boolean isEnabled() throws IllegalActionException
    {
        return _isEnabled;
    }

    /** Add a ProvenanceEnabledListener to be notified when provenance
     *  is enabled/disabled.
     */
    public void addEnabledListener(ProvenanceEnabledListener listener)
    {
        boolean contain = false;
                for (int i = 0; i < _enabledListeners.size(); i++) {
                        WeakReference<ProvenanceEnabledListener> reference = _enabledListeners.get(i);
                        ProvenanceEnabledListener _listener = reference.get();
                        if(_listener != null && _listener == listener) {
                                contain = true;
                                break;
                        }else if (listener == null ){
                                _enabledListeners.remove(i);
                                i--;
                        }
                        
                }
        if(!contain)
        {
            _enabledListeners.add(new WeakReference<ProvenanceEnabledListener>(listener));   
        }
        listener.toggle(_isEnabled);
    }
    
    /** Remove a ProvenanceEnabledListener from the set of listeners.*/
    public void removeEnabledListener(ProvenanceEnabledListener listener)
    {
                for (int i = 0; i < _enabledListeners.size(); i++) {
                        WeakReference<ProvenanceEnabledListener> reference = _enabledListeners.get(i);
                        ProvenanceEnabledListener _listener = reference.get();
                        if(_listener != null && _listener == listener) {
                                _enabledListeners.remove(i);
                                i--;
                        }else if (listener == null ){
                                _enabledListeners.remove(i);
                                i--;
                        }
                        
                }
    }
    
    ///////////////////////////////////////////////////////////////////
    //// Initializable interface                                   ////
    
    /** This function is called when the manager is about to run the model
     * and allows us to register with the manager before the run happens.
     * We would do this in our constructor but the manager is not created
     * until the user starts executing the workflow for the first time.
     */
    @Override
    public void preinitialize() throws IllegalActionException 
    {
        //_Debug("preinitialize()");

        
        if(_initializables != null)
        {
            for(Initializable initializable : _initializables)
            {
                initializable.preinitialize();
            }
        }

        if(checkForSupportedDirector())
        {
                _amExecuting = true;
        
            CompositeActor topLevel = (CompositeActor)getContainer();
            Manager manager = topLevel.getManager();
            
            if(!_addedExecutionListener) 
            {
                manager.addExecutionListener(this);
                _addedExecutionListener = true; 
            }
            
            // if requested, record contents of workflow
            _recordWorkflowContents();

            // verify all composites containing provenance recorders are opaque
            for(CompositeActor composite : _provOpaqueSet)
            {
                if(!composite.isOpaque())
                {
                    String msgStr = "Composite " + composite.getFullName() + 
                        " is transparent\n(does not have a director), and " +
                        "contains an instance of the Provenance Recorder.\n" +
                        "The Provenance Recorder can only be placed in " +
                        "opaque composite actors.";
                    
                    _debugWrite(msgStr);

                    throw new IllegalActionException(this, msgStr);
                }
            }

            _haveExecuted = true;

            if(_provStore == null)
            {
                throw new IllegalActionException(this,
                    "Invalid recording type: " + recordingType.stringValue());
            }
            else
            {
                
                // process any delayed events
                while(_delayedEventList.size() > 0)
                {
                    DelayedEvent event = _delayedEventList.remove(0);
                    if(event.isAdd())
                    {
                        tagAdded((TagEvent)event.getEvent());
                    }
                    else
                    {
                        tagRemoved((TagEvent)event.getEvent());
                    }
                }
                
                // generate LSID for this execution
                try
                {
                    _executionLSID = LSIDGenerator.getInstance().getNewLSID();
                }
                catch(Exception e)
                {
                    throw new IllegalActionException(this, e, "Error generating new LSID for " +
                        "workflow execution.");
                }

                // set the execution identifier in the manager
                manager.setExecutionIdentifier(_executionLSID);

                try
                {
                    // record start of new workflow execution
                    Date timestamp = new Date();
                    _provStore.executionStart(_executionLSID, timestamp);
                    
                    // notify any piggybacks
                    for(Recording recording : _piggybacks)
                    {
                        recording.executionStart(_executionLSID, timestamp);
                    }
                }
                catch(RecordingException e)
                {
                    throw new IllegalActionException(this, e, "Error recording execution start.");
                }
            }
        }
    }

    /** Invoke the initialize methods and check for additional
     *  MultiInstanceComposite actors created after preinitialize().
     *  of objects that have been added using addInitializable().
     *  @exception IllegalActionException If one of the added objects
     *   throws it.
     */
    @Override
    public void initialize() throws IllegalActionException
    {
        // initialize our Initializables
        if(_initializables != null)
        {
            for(Initializable initializable : _initializables)
            {
                initializable.initialize();
            }
        }

        CompositeEntity container = (CompositeEntity)getContainer();
        
        // look for additional multi instance composite clones
        
        for(String masterName : _multiInstanceCompositeMasterNames)
        {
            int i = 1;
            // XXX identifying clones by a specific name is fragile.
            String cloneName = masterName + "_" + i;
            NamedObj mic = container.getEntity(cloneName);
            while(mic != null)
            {
                if(! _multiInstanceCompositeClones.contains(mic))
                {
                    // register the new multi instance composite
                    
                    try
                    { 
                        _provStore.evolutionStart();
                        
                        for(Recording recording : _piggybacks)
                        {
                            recording.evolutionStart();
                        }

                        _recordContainerContents(mic);
                        
                        // register its relations
                        List<IORelation> relationList = ((Entity<?>)mic).linkedRelationList();
                        for(IORelation relation : relationList)
                        {
                            _recordContainerContents(relation);
                            
                            // register the the links
                            _recordLinksInRelation(relation);
                        }

                        _provStore.evolutionStop();

                        for(Recording recording : _piggybacks)
                        {
                            recording.evolutionStop();
                        }

                    }
                    catch(RecordingException e)
                    {
                        throw new IllegalActionException(this, e, "Error registering new MultiInstanceComposites");
                    }   
                }
                
                i++;
                cloneName = masterName + "_" + i;
                mic = container.getEntity(cloneName);
            }
        }
        
        // clear the multi instance composite sets so that they are empty
        // at the beginning of each run.
        _multiInstanceCompositeClones.clear();
        _multiInstanceCompositeMasterNames.clear();
    }
        
    /** Perform clean up. This method is executed when the manager is
     *  finishing model execution.
     */
    @Override
    public void wrapup() throws IllegalActionException
    {
        //_Debug("wrapup()");
        
        if(_amExecuting)
        {
                try
                {
                    Date timestamp = new Date();
                    _provStore.executionStop(_executionLSID, timestamp);
                    
                    // notify any piggybacks
                    for(Recording recording : _piggybacks)
                    {
                        recording.executionStop(_executionLSID, timestamp);
                    }
                    
                    _executionLSID = null;
                }
                catch(RecordingException e)
                {
                    throw new IllegalActionException(this, e, "Error recording execution stop.");
                }
        
                _amExecuting = false;
        }
        
        // tell initializables to wrapup.
        // NOTE: we do this after recording execution stop since the 
        // initializables wrapup may rely on workflow execution to
        // have finished.
        if(_initializables != null)
        {
            for(Initializable initializable : _initializables)
            {
                initializable.wrapup();
            }
        }
    }
  
    /** Add the specified object to the list of objects whose
     *  preinitialize(), intialize(), and wrapup()
     *  methods should be invoked upon invocation of the corresponding
     *  methods of this object.
     *  @param initializable The object whose methods should be invoked.
     *  @see #removeInitializable(Initializable)
     *  @see ptolemy.actor.CompositeActor#addPiggyback(Executable)
     */
    @Override
    public void addInitializable(Initializable initializable)
    {
        if (_initializables == null)
        {
            _initializables = new LinkedList<Initializable>();
        }
        _initializables.add(initializable);
    }

    /** Remove the specified object from the list of objects whose
     *  preinitialize(), intialize(), and wrapup()
     *  methods should be invoked upon invocation of the corresponding
     *  methods of this object. If the specified object is not
     *  on the list, do nothing.
     *  @param initializable The object whose methods should no longer be 
     *  invoked.
     *  @see #addInitializable(Initializable)
     *  @see ptolemy.actor.CompositeActor#removePiggyback(Executable)
     */
    @Override
    public void removeInitializable(Initializable initializable)
    {
        if(_initializables != null)
        {
            _initializables.remove(initializable);
            if(_initializables.size() == 0)
            {
                _initializables = null;
            }
        }
    }
 
    ///////////////////////////////////////////////////////////////////
    //// ChangeListener interface                                  ////

    /** React to a change request has been successfully executed.
     *  
     *  @param change The change that has been executed, or null if
     *   the change was not done via a ChangeRequest.
     */
    //TODO: NEED TO ADD LISTENERS TO NEWLY ADDED ACTORS AND PORTS!!!
    @Override
    public void changeExecuted(ChangeRequest change)
    {

        // check to make sure we were not removed from the model
        // NOTE: we stop listening for change events when removed
        // from model, but sometimes an event can be queued before
        // we stop listening. we need to ignore them since in
        // setContainer() we told the recording to disconnect.
        if(! _removedFromModel)
        {
            synchronized(this)
            {
                boolean recordContents = false;
                    
                //_Debug("Model change: " + change.getDescription());
                //_Debug("Change made by: " + change.getSource());
    
                if(change instanceof MoMLChangeRequest)
                {
                    //_Debug("Model change: " + change.getDescription());
                    //_Debug("Change made by: " + change.getSource());
    
                    MoMLChangeRequest momlChange = (MoMLChangeRequest)change;
                    NamedObj context = momlChange.getContext();
    
                    //_Debug("context = " + context.getFullName());
    
                    // ignore changes made us
                    if(context != this)
                    {
                        recordContents = true;
                    }
                }

                // record the contents of the model unless we are executing
                // or are delaying recording specification. NOTE: if we ignore
                // the latter, this causes the model to be recorded for every
                // moml change request, which is very slow for large models.
                // see http://bugzilla.ecoinformatics.org/show_bug.cgi?id=4764
                if(recordContents && !_amExecuting && !_delayRecordingSpecificationVal)
                {
                        try 
                        {
                                                if(checkForSupportedDirector())
                                                {
                                                    try
                                                    {
                                                        //_Debug("Model change: " + change.getDescription());
                                                        //_Debug("Change made by: " + change.getSource());
                                                        _recordWorkflowContents();
                                                    }
                                                    catch(IllegalActionException e)
                                                    {
                                                        _debugWrite("ERROR trying to record workflow " +
                                                            "contents: " + e.getMessage());
                                                    }
                                                }
                                        }
                        catch (IllegalActionException e) 
                        {
                                MessageHandler.error("Error checking for supported director.", e);
                                        }
                }
            }
        }
    }

    /** React to a change request has resulted in an exception.
     *  
     *  @param change The change that was attempted or null if
     *   the change was not done via a ChangeRequest.
     *  @param exception The exception that resulted.
     */
    @Override
    public void changeFailed(ChangeRequest change, Exception exception)
    {
        System.out.println("Change failed: " + change.getDescription());
        System.out.println("Change made by: " + change.getSource());
        System.out.println("Exception: " + exception.getMessage());
    }
    
    ///////////////////////////////////////////////////////////////////
    //// ExecutionListener interface                               ////

    /** Report an execution failure.   This method will be called
     *  when an exception or error is caught by a manager.
     *  Exceptions are reported this way when the run() or startRun()
     *  methods of the manager are used to perform the execution.
     *  If instead the execute() method is used, then exceptions are
     *  not caught, and are instead just passed up to the caller of
     *  the execute() method.  Those exceptions are not reported
     *  here (unless, of course, the caller of the execute() method does
     *  so).
     *
     *  @param manager The manager controlling the execution.
     *  @param throwable The throwable to report.
     */
    @Override
    public void executionError(Manager manager, Throwable throwable) 
    {
        if(_provStore != null)
        {
            // get the execution lsid
            KeplerLSID executionLSID = (KeplerLSID)manager.getExecutionIdentifier(throwable);
                         
            if(executionLSID == null)
            {
                System.out.println("ERROR: no LSID for throwable: " + throwable.getMessage());
                throwable.printStackTrace();
            }
            else
            {
                // see if there's a source
                Nameable source = null;
                if(throwable instanceof KernelException)
                {
                    source = ((KernelException)throwable).getNameable1(); 
                }
           
                try
                {
                    _provStore.executionError(source, throwable, executionLSID);
                
                    // notify any piggybacks
                    for(Recording recording : _piggybacks)
                    {
                        recording.executionError(source, throwable, executionLSID);
                    }
                }
                catch(RecordingException e)
                {
                    _debugWrite("Error recording execution error: " +
                        e.getMessage());
                }
            }
        }
    }
    
    /** Report that the current execution has finished and the wrapup 
     *  sequence has completed normally. 
     *
     *  @param manager The manager controlling the execution.
     */
    @Override
    public void executionFinished(Manager manager) 
    {
    }
    
    /** Report that an execution has been imported */
    public void executionImported(KeplerLSID execLSID){
        // notify any piggybacks
        for(Recording recording : _piggybacks)
        {
                recording.executionImported(execLSID);
        }
    }
    
    /** Report that the manager has changed state.
     *
     *  @param manager The manager controlling the execution.
     */
    @Override
    public void managerStateChanged(Manager manager)
    {
        //Manager.State state = manager.getState();
        //_Debug("managerStateChanged " + state.getDescription());
    }
    
    ///////////////////////////////////////////////////////////////////
    //// IOPortEventListener interface                               ////

    /** React to a port read or write.
     *  
     *  @param event The event representing the token(s).
     */
    @Override
    public void portEvent(IOPortEvent event) throws IllegalActionException
    {
        if(_recordTokensVal)
        {
            try
            {
                boolean ignore = false;
                IOPort port = event.getPort();
                int type = event.getEventType();
            
                NamedObj container = (NamedObj)port.getContainer();
    
                // see if the port's container is our container
                if(container == getContainer())
                {
                    // ignore events outside our container
                    if((port.isInput() && 
                        (type == IOPortEvent.GET_BEGIN ||
                        type == IOPortEvent.GET_END)) ||
                        (port.isOutput() &&
                        (type == IOPortEvent.SEND_BEGIN ||
                         type == IOPortEvent.SEND_END)))
                    {
                        ignore = true;        
                    }
                }
                // see if the port's container has a ProvenanceRecorder
                else if((container instanceof CompositeActor) && 
                    _provOpaqueSet.contains((CompositeActor)container))
                {
                    // ignore events inside composite actor
                    if((port.isInput() &&
                        (type == IOPortEvent.SEND_BEGIN ||
                        type == IOPortEvent.SEND_END)) ||
                        (port.isOutput() &&
                        (type == IOPortEvent.GET_BEGIN ||
                        type == IOPortEvent.GET_END)))
                    {
                        ignore = true;        
                    }
                }

                if(!ignore)
                {
                    _provStore.portEvent(event);
                    
                    // notify any piggybacks
                    for(Recording recording : _piggybacks)
                    {
                        recording.portEvent(event);
                    }
                }

                /*
                IOPort srcPort = event.getPort();
                int srcType = event.getEventType();
                int newType;
                IOPort newPort = null;

                if(!srcPort.isOpaque() && srcType == IOPortEvent.GET_END)
                {
                    newType = IOPortEvent.SEND;
                    newPort = srcPort;
                }
                else
                {
                    newType = IOPortEvent.GET_END;
                }
            
                // send an event for each connected port in table
                List<IOPort> connPorts = _portConnTable.get(srcPort);
                if(connPorts != null)
                {
                    for(IOPort destPort : connPorts) 
                    {
                        IOPortEvent newEvent = null;
                  
                        if(newType == IOPortEvent.GET_END)
                        {
                            newPort = destPort; 

                            // do not make a fake receive event for opaque ports.
                            if(destPort.isOpaque())
                            {
                                continue;
                            }
                        }

                        //_Debug("resending " + destPort);
                    
                        if(event.getVectorLength() == IOPortEvent.SINGLETOKEN)
                        {
                            newEvent = new IOPortEvent(newPort, newType,
                                event.getChannel(), event.getOutsideFlag(), 
                                event.getToken());
                        }
                        else
                        {
                            newEvent = new IOPortEvent(newPort, newType,
                                event.getChannel(), event.getOutsideFlag(), 
                                event.getTokenArray(), event.getVectorLength());
                        }

                        _Debug("FAKE");
                        portEvent(newEvent);
                    }
                }
                */
            }
            catch(RecordingException e)
            {
                // this is not necessarily an error since it may
                // be expected (e.g., port condition). 
                //_debugWrite("ERROR: RecordingException: " + e.getMessage());
                
                Throwable cause = e.getCause();
                if(cause != null && (cause instanceof IllegalActionException))
                {
                    throw (IllegalActionException)cause;
                }
            }
        }
    }
    
    ///////////////////////////////////////////////////////////////////
    //// ActorFiringListener interface                             ////
    
    /** React to an actor firing.
     *  
     *  @param event The event representing the token(s) sent.
     */
    @Override
    public void firingEvent(FiringEvent event) 
    {
        Actor actor = event.getActor();
        
        // see if this actor has been registered.
        if(! _firingEventSenders.contains(actor))
        {
            /*
            System.out.println("firing from unregistered actor: " +
                actor.getFullName());
            
            new Exception().printStackTrace(System.out);
            */
            
            try
            {
                _provStore.evolutionStart();
                
                for(Recording recording : _piggybacks)
                {
                    recording.evolutionStart();
                }
                
                _recordContainerContents((NamedObj)actor);
                
                _provStore.evolutionStop();
                
                for(Recording recording : _piggybacks)
                {
                    recording.evolutionStop();
                }
            }
            catch(RecordingException e) 
            {
                System.out.println("Error recording container contents: " +
                    e.getMessage());
            }
        }
        
        try
        {
            _provStore.actorFire(event);
            
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.actorFire(event);
            }
        }
        catch(RecordingException e)
        {
            _debugWrite("Error recording actor firing: " + e.getMessage());
        }
    }

    ///////////////////////////////////////////////////////////////////
    //// DebugListener interface                                   ////
  
    /** React to a generic debug event. Actors and directors may use
     * this interface to inform listeners of firing events.
     */
    @Override
    public void event(DebugEvent event)
    {
        if(event instanceof FiringEvent)
        {
            firingEvent((FiringEvent)event);
        }
        else if(event instanceof ProvenanceEvent)
        {
            try
            {
                _provStore.customProvEvent((ProvenanceEvent)event);
                
                // notify any piggybacks
                for(Recording recording : _piggybacks)
                {
                    recording.customProvEvent((ProvenanceEvent)event);
                }
            }
            catch(RecordingException e)
            {
                System.out.println("ERROR: RecordingException: " + 
                    e.getMessage());
            }
        }
        else if(event instanceof IOPortEvent)
        {
            try
            {
                portEvent((IOPortEvent)event);
            }
            catch (IllegalActionException e)
            {
                System.out.println("ERROR: port event: " + e.getMessage());
            }
        }
        else if(event instanceof IOPortRefillEvent)
        {
            try
            {
                _provStore.refillPortEvent((IOPortRefillEvent)event);
                
                for(Recording recording : _piggybacks)
                {
                    recording.refillPortEvent((IOPortRefillEvent)event);
                }
            }
            catch(RecordingException e)
            {
                System.out.println("ERROR: RecordingException: " +
                    e.getMessage());
            }
        }
    }

    /** Add a recording type. */
    public void addRecordingType(String typeName, String typeImpl) 
        throws IllegalActionException
    {
        _recordingTypesMap.put(typeName, typeImpl);
        _populateChoices();
    }

    /** Remove a recording type. */
    public void removeRecordingType(String typeName)
        throws IllegalActionException
    {
        if(_recordingTypesMap.remove(typeName) == null)
        {
            throw new IllegalActionException(this, 
                "No such Recording type to remove: " + typeName);
        }
        _populateChoices();
    }

    /** Load the default recording types. */
    public void loadRecordingTypes() throws IllegalActionException
    {
        ConfigurationProperty typesProp = 
            ConfigurationManager.getInstance().getProperty(
            ConfigurationManager.getModule("provenance"), "provenance.recordingTypes");
        _recordingTypesMap = ConfigurationUtilities.getPairsMap(typesProp);
        
        // make sure all keys and values are not empty.
        for(Map.Entry<String, String> entry : _recordingTypesMap.entrySet())
        {
            String key = entry.getKey();
            String value = entry.getValue();
            if(key == null || key.trim().length() == 0)
            {
                throw new IllegalActionException(this,
                    "Missing key in recording types.");
            }
            else if(value == null || value.trim().length() == 0)
            {
                throw new IllegalActionException(this,
                    "Missing value in recording types.");
            }
        }
        _populateChoices();
    }
    
    /** Load the recording types from a specific file. */
    public void loadRecordingTypes(File file) throws IllegalActionException
    {
        _recordingTypesMap = new HashMap<String,String>();

        Properties propFile = new Properties();
        InputStream is = null;
        // attempt to load the properties file.
        try
        {
            is = new FileInputStream(file);
            propFile.load(is);
        }
        catch(FileNotFoundException e)
        {
            throw new IllegalActionException(this, "Cannot load recording " +
                "types from " + file + ": " + e.getMessage());
        }
        catch(IOException e)
        {
            throw new IllegalActionException(this, 
                "Error reading " + file + ": " + e.getMessage());
        }
        finally
        {
            if(is != null)
            {
                try
                {
                    is.close();
                }
                catch(IOException e)
                {
                    System.out.println("Unable to close " + file + ": " + e.getMessage());
                }
            }
        }
        
        for(Map.Entry<Object, Object> entry : propFile.entrySet())
        {
            _recordingTypesMap.put((String)entry.getKey(),
                (String)entry.getValue()); 
        }

        _populateChoices();
    }
    
    /** Save the recording types to a specific properties file.
     *
     *  @param file the properties file path.
     *  @param header optional header for properties file.
     */
    public void saveRecordingTypes(String file, String header)
        throws IllegalActionException
    {
        Properties propFile = new Properties();
        for(Map.Entry<String, String> entry : _recordingTypesMap.entrySet())
        {
            propFile.setProperty(entry.getKey(), entry.getValue());
        }
        
        OutputStream out = null;
        try
        {   
            out = new FileOutputStream(file);
            propFile.store(out, header);
        }
        catch(FileNotFoundException e)
        {
            throw new IllegalActionException(this,
                "FileNotFoundException when trying to write to " + file +
                    ": " + e.getMessage());
        }
        catch(IOException e)
        {
            throw new IllegalActionException(this,
                "IOException when trying to write to " + file + ": " +
                    e.getMessage());
        }
        finally
        {
            if(out != null)
            {
                try
                {
                    out.close();
                }
                catch(IOException e)
                {
                    System.out.println("Unable to close " + file + ": " + e.getMessage());
                }
            }
        }
    }

    ///////////////////////////////////////////////////////////////////
    //// ValueListener interface                                   ////
 
    /** React to a change in parameter value. */
    @Override
    public void valueChanged(Settable settable)
    {
        try
        {
            _workspace.getWriteAccess();
            
            // ignore the settable if it's pending
            if(_pendingSettables.contains(settable))
            {
                return;
            }
            else
            {
                _pendingSettables.add(settable);
            }

            String name = _valueEventSenders.get(settable);

            // if the names do not match, then the parameter was
            // removed from the model.
            if(name == null || 
                ! name.equals(((NamedObj)settable).getFullName()))
            {
                // remove the cached last value.
                _paramValueTable.remove(settable);
            }
            else
            {
                // NOTE: calling getValueAsString() may generate
                // another valueChanged event, so we do that first
                // before retrieving the old value from the table.
                //
                // the following function call sequence can occur:
                //
                // valueChanged() -> getValueAsString() -> valueChanged()
                //      A                   B                   C
                //
                // if we retrieve the old value in A before calling
                // B, then the update that C makes will not be found.
                // in this case, A will always find the old value
                // different from the current value.
                //
                // instead, we retrieve the old value in A after calling
                // B so that C has updated the table.
                //
                
                String newVal = settable.getValueAsString();
                
                String oldVal = _paramValueTable.get(settable);
                if(oldVal == null || !oldVal.equals(newVal))
                {
                    /*
                    _Debug("changed value: " + 
                        ((NamedObj)settable).getFullName() + " to = " + newVal);
                    */

                    _paramValueTable.put(settable, newVal);

                    try
                    {
                        _provStore.evolutionStart();                        
                        _provStore.regParameter((NamedObj)settable);
                        _provStore.evolutionStop();
                        
                        // notify any piggybacks
                        for(Recording recording : _piggybacks)
                        {
                            recording.evolutionStart();
                            recording.regParameter((NamedObj)settable);
                            recording.evolutionStop();
                        }

                        
                    }
                    catch(RecordingException e)
                    {
                        _debugWrite("ERROR recording value change: " + 
                            e.getMessage());
                    }
                }
                    
               _pendingSettables.remove(settable);
            }
        }
        finally
        {
            // we didn't change the workspace, so call doneTemporaryWriting()
            // so that the workspace version is not incremented.
            _workspace.doneTemporaryWriting();
        }
    }

    ///////////////////////////////////////////////////////////////////
    //// SshEventListener interface                                ////
  
    /** React to an ssh event. */
    @Override
    public void sshEvent(SshEvent event)
    {
        // XXX no implementation yet.
    }
    
    ///////////////////////////////////////////////////////////////////
    //// WorkflowRenameListener interface                    ////
    
    /** A workflow was renamed.
     * 
     * @param namedObj the workflow
     * @param oldLSID the previous LSID
     * @param newLSID the new LSID
     * @param oldName the previous name
     * @param newName the new name
     * @see WorkflowRenameListener
     */
    @Override
    public void renamedWorkflow(NamedObj namedObj, KeplerLSID oldLSID,
        KeplerLSID newLSID, String oldName, String newName)
    {
        // make sure the workflow is our container since we receive
        // rename events for all open workflows.
        if(namedObj == getContainer())
        {
            if(_provStore != null)
            {
                                try 
                                {
                                        _provStore.renamedWorkflow(namedObj, oldLSID, newLSID, oldName,
                                                        newName);

                                        // notify any piggybacks
                                        for (Recording recording : _piggybacks) 
                                        {
                                                recording.renamedWorkflow(namedObj, oldLSID, newLSID,
                                                                oldName, newName);
                                        }
                                } 
                                catch (RecordingException e) 
                                {
                                        // TODO Auto-generated catch block
                                        e.printStackTrace();
                                }
            }
        }
    }
    
    ///////////////////////////////////////////////////////////////////
    //// TagEventListener interface                                ////
    
    @Override
    public void tagAdded(TagEvent event)
    {
                _delayRecordingSpecificationVal = false;
                try {
                        NamedObj tagEventSource = event.getSource();
                        if (!(tagEventSource instanceof WorkflowRun)) {
                                _recordWorkflowContents();
                        }
                }
                catch(IllegalActionException ex) {
                        log.error("Failed to record workflow", ex);
                }

        if(_haveExecuted || !_delayRecordingSpecificationVal)
        {
            try
            {
                _provStore.tagAdded(event);
                // notify any piggybacks
                for(Recording recording : _piggybacks)
                {
                    recording.tagAdded(event);
                }
            }
            catch(RecordingException e)
            {
                System.out.println("Error adding tag: " + e.getMessage());             
            }
        }          
        else
        {
            // queue the event
            DelayedEvent delayed = new DelayedEvent(event, true);
            _delayedEventList.add(delayed);
        }
    }
    
    @Override
    public void tagRemoved(TagEvent event)
    {
                _delayRecordingSpecificationVal = false;
                try {
                        NamedObj tagEventSource = event.getSource();
                        if (!(tagEventSource instanceof WorkflowRun)) {
                                _recordWorkflowContents();
                        }
                }
                catch(IllegalActionException ex) {
                        log.error("Failed to record workflow", ex);
                }
        
        if(_haveExecuted || !_delayRecordingSpecificationVal)   
        {
            try
            {
                _provStore.tagRemoved(event);
                // notify any piggybacks
                for(Recording recording : _piggybacks)
                {
                    recording.tagRemoved(event);
                }
            }
            catch(RecordingException e)
            {
                System.out.println("Error removing tag: " + e.getMessage());
            }

        }  
        else
        {
            // queue the event
            DelayedEvent delayed = new DelayedEvent(event, false);
            _delayedEventList.add(delayed);
        }
    }


    ///////////////////////////////////////////////////////////////////
  
    /** Set a writer for debugging output. */
    public void setDebugWriter(Writer writer)
    {
        _debugWriter = writer;
        if(_provStore != null)
        {
            _provStore.setDebugWriter(writer);
        }
    }
    
    /** Get the provenance recorder with for a NamedObj. The "default"
     *  provenance recorder for a NamedObj is stored at the top level of
     *  the hierarchy and is named using the TOP Recorder Name in the
     *  configuration file. If no default recorder exists, returns null.
     */
    public static ProvenanceRecorder getDefaultProvenanceRecorder(NamedObj namedObj)
    {
        Map<String,String> defaultsMap = getDefaultsMap();
        String name = defaultsMap.get(_DEFAULT_NAME);
        
        NamedObj top = namedObj.toplevel();
        return (ProvenanceRecorder)top.getAttribute(name);
    }
    
    /** Get a queryable from the default provenance recorder for a NamedObj.
     *  The "default" provenance recorder for a NamedObj is stored at the top
     *  level of the hierarchy and is named using the TOP Recorder Name in
     *  the configuration file. If no default recorder exists, returns null.
     *  If the NamedObj is null, this returns the Queryable for the default
     *  provenance recording.
     */
    public static Queryable getDefaultQueryable(NamedObj namedObj)
        throws QueryException, RecordingException
    {
        ProvenanceRecorder recorder = null;
        
        if(namedObj != null) {
            recorder = getDefaultProvenanceRecorder(namedObj);
        
            if(recorder != null)
            {
                Recording recording = recorder.getRecording();
                if(recording != null)
                {
                    return recording.getQueryable(true);
                }
            }
        }
        
        try {
            recorder = new ProvenanceRecorder();
        } catch (IllegalActionException | NameDuplicationException e) {
            throw new RecordingException("Unable to create ProvenanceRecorder.", e);
        }
        return recorder.getRecording().getQueryable(false);        
    }

    /** Get current RecordingParameters. XXX how does this differ from
     *  attributeList()?
     */
    public RecordingParameters getRecordingParameters()
    {
        return _provStoreParams;
    }

    /** Get the current recording. */
    public Recording getRecording()
    {
        return _provStore; 
    }

    /** Set the persistence of parameters. */
    public void setPersistentParameters(boolean persistent)
    {
        username.setPersistent(persistent);
        hostname.setPersistent(persistent);
        containerWorkflowLSID.setPersistent(persistent);
        containerWorkflowName.setPersistent(persistent);
        delayRecordingSpecification.setPersistent(persistent);
        recordTokens.setPersistent(persistent);
        recordingType.setPersistent(persistent);
        
        if(_provStoreParams != null)
        {
            _provStoreParams.setPersistent(persistent);
        }
    }
    
    /** Add the specified recording to the list of recordings notified
     *  for each provenance event. NOTE: the recordings are notified
     *  <b>after</b> the internal Recording.
     *  
     *  @param recording the Recording to be notified
     */
    public void addPiggyback(Recording recording)
    {
        if(!_piggybacks.contains(recording))
        {
            _piggybacks.add(recording);
            recording.setContainer(this);
        }
    }
    
    /** Remove the specified recording from the list of recordings
     *  notified for each provenance event.
     *  
     *  @param recording the Recording to remove
     *  @see ProvenanceRecorder#addPiggyback
     */
    public void removePiggyback(Recording recording)
    {
        _piggybacks.remove(recording);
        recording.setContainer(null);
    }
    
    /** Add the specified recording to the list of recordings that receive
     *  provenance events from all ProvenanceRecorders created in the
     *  future. NOTE: this does not include existing ProvenanceRecorders.
     *  
     * @param recording the Recording to be notified
     */
    public static void addPiggybackForFuture(Recording recording)
    {
        if(!_futurePiggybacks.containsKey(recording))
        {
            _futurePiggybacks.put(recording, null);
        }
    }
    
    /** Remove the specified recording from the list of recordings that
     *  receive provenance events from all ProvenanceRecorders created
     *  in the future.
     *  
     *  @param recording the Recording to remove
     *  @see ProvenanceRecorder#addPiggybackForFuture
     */
    public static void removePiggybackForFuture(Recording recording)
    {
        _futurePiggybacks.remove(recording);
    }
    
    /** Return list of recordings that receive provenance events from all
     *  ProvenanceRecorders created in the future.
     * @param recording
     * @return _futurePiggybacks
     */
    public static List<Recording> getFuturisticPiggybacks(Recording recording)
    {
        List<Recording>  recordings = new LinkedList<Recording>();
        Iterator<Recording> _futurePiggybacksKeyIt = _futurePiggybacks.keySet().iterator();
        while (_futurePiggybacksKeyIt.hasNext())
        {
                Recording record = _futurePiggybacksKeyIt.next();
                if (record != null)
                        recordings.add(record);
        }
        return recordings;
    }

    /** Returns true if the composite actor contains a director supported
     *  by the provenance recorder or no director.
     */
    public static boolean containsSupportedDirector(CompositeActor composite)
    {
        boolean retval = false;
        
        Director director = composite.getDirector();
        if(director == null ||
            (director instanceof SDFDirector) ||
            (director instanceof DDFDirector) ||
            (director instanceof PNDirector) ||
            
            // DE director sends actor firing events to listeners
            // of the director instead of listeners of the actors,
            // so provenance recording is not fully supported.
            //(director instanceof DEDirector) ||
            
            // IterateOverArray uses IterateDirector, which is
            // private
            (composite instanceof IterateOverArray) ||
            (director instanceof CaseDirector))
        {
            retval = true;
        }       
        
        return retval;
    }
    
    /** Check if the director is supported. If it is not, then provenance
     *  recording is turned off.
     */
    public boolean checkForSupportedDirector() throws IllegalActionException
    {
        boolean retval = containsSupportedDirector((CompositeActor)getContainer());
        
        if(!retval)
        {
                recordingType.setToken(ProvenanceRecorder.DEFAULT_REC_TYPE_IGNORE);
        }
        
        return retval;
    }
    
    /** Get the execution LSID. If the model is not running,
     *  returns null.
     */
    public KeplerLSID getExecutionLSID()
    {
        return _executionLSID;
    }
    
    /** Add the default provenance recorder to a container if it does not
     *  already contain a provenance recorder.
     *  
     *  @param container The container in which to add the default provenance
     *  recorder.
     *  @param listener Register this object to listen for provenance enabled
     *  events. This parameter can be null.
     *  @param effigy The effigy displaying the container. This parameter can
     *  be null.
     *  @return Returns true if the default provenance recorder is recording.
     *  This may be false due to an unsupported director in container, or the
     *  default recording type set to ignore.
     *  
     */
    public static boolean addProvenanceRecorder(CompositeActor container,
        ProvenanceEnabledListener listener, Effigy effigy) 
        throws IllegalActionException, NameDuplicationException
    {
        
        Map<String,String> defaultsMap = getDefaultsMap();
        String defaultName = defaultsMap.get(_DEFAULT_NAME);

        ProvenanceRecorder defaultRecorder = null;
        List<?> recorderList = container.attributeList(ProvenanceRecorder.class);
        for(Object object : recorderList)
        {
            final ProvenanceRecorder recorder = (ProvenanceRecorder)object;
            
            // see if this is the default
            if(recorder.getName().equals(defaultName))
            {
                defaultRecorder = recorder;
                break;
            }          
        }
        
        // see if there were no other provenance recorders
        if(recorderList.isEmpty())
        {
            // add the default provenance recorder            
            defaultRecorder = new ProvenanceRecorder(container);
                                   
            // set the workflow name to be the model name
            String wfNameStr = container.getName();
            
            Parameter wfNameParameter =
                (Parameter)defaultRecorder.getAttribute(SQLRecordingParameters.wfNameParamStr);
            
            // see if it was found (not all recording types have this parameter)
            if(wfNameParameter != null)
            {
                wfNameParameter.setToken(wfNameStr);
            }
            
            if(listener != null)
            {
                defaultRecorder.addEnabledListener(listener);
            }
            
            // do not save in moml
            defaultRecorder.setPersistent(false);
        }
        
        boolean enabled = false;
        
        // see if we found the default recorder
        if(defaultRecorder != null)
        {        
            // see if the director is supported
            if(!ProvenanceRecorder.containsSupportedDirector(container))
            {
                // turn off recording
                defaultRecorder.recordingType.setToken(ProvenanceRecorder.DEFAULT_REC_TYPE_IGNORE);
            }
            else
            {                              
                // get the default recording type
                Map<String,String> map = ProvenanceRecorder.getDefaultsMap();
                String recordingType = map.get(_RECORDING_TYPE);
                
                defaultRecorder.recordingType.setToken(recordingType);
                enabled = defaultRecorder.isEnabled();
            }
            
            // see if the default provenance recorder was stored in the moml
            if(defaultRecorder.isPersistent() && effigy != null)
            {
                System.out.println("removing PR from moml");
                defaultRecorder.setPersistent(false);
                effigy.setModified(true);
            }
            
        }
    
        // causes new (blank) workflows to prompt for save 
        // see: http://bugzilla.ecoinformatics.org/show_bug.cgi?id=4200
        //_effigy.setModified(true);    
        
        return enabled;
    }
    
    /** Set the state serializer for recordings. */
    public void setStateSerializer(StateSerializer serializer)
    {
        _stateSerializer = serializer;
        
        if(_provStore != null)
        {
            _provStore.setStateSerializer(serializer);
        }
        
        // notify any piggybacks
        for(Recording recording : _piggybacks)
        {
            recording.setStateSerializer(serializer);
        }
    }
    
    /** Remove the state serializer. */
    public void removeStateSerializer()
    {
        _stateSerializer = null;
        
        if(_provStore != null)
        {
            _provStore.removeStateSerializer();
        }

        // notify any piggybacks
        for(Recording recording : _piggybacks)
        {
            recording.removeStateSerializer();
        }
    }
    
    ///////////////////////////////////////////////////////////////////
    ////                      private methods                    //////
         
    /** Initialize the provenance execution listener. */
    private synchronized void _init() 
        throws IllegalActionException, NameDuplicationException 
    {
        _attachText("_iconDescription", "<svg>\n" +
                "<rect x=\"-50\" y=\"-15\" "
                + "width=\"100\" height=\"30\" "
                + "style=\"fill:blue\"/>\n" +
                "</svg>\n");
       
        _addedExecutionListener = false;
        _amExecuting = false;
        _changeEventSenders = new HashSet<NamedObj>();
        _curRecordingTypeStr = null;
        _debugEventSenders = new HashSet<Debuggable>();
        _debugWriter = null;
        _delayedEventList = new LinkedList<DelayedEvent>();
        _enabledListeners = new LinkedList<WeakReference<ProvenanceEnabledListener>>();
        _executionLSID = null;
        _firingEventSenders = new HashSet<FiringsRecordable>();
        _haveExecuted = false;
        _initializables = null;
        _isEnabled = true;
        _multiInstanceCompositeClones = new HashSet<MultiInstanceComposite>();
        _multiInstanceCompositeMasterNames = new HashSet<String>();
        _paramValueTable = new Hashtable<Settable,String>();
        _pendingSettables = new HashSet<Settable>();
        _piggybacks = new LinkedList<Recording>(_futurePiggybacks.keySet());
        _plParams = new LinkedHashSet<String>();
        _portEventSenders = new HashSet<IOPort>();
        _possibleRecordingAttributes = new HashSet<Attribute>();
        //_portConnTable = new Hashtable<IOPort,List<IOPort>>();
        _provOpaqueSet = new HashSet<CompositeActor>();
        _provStore = null;        
        _provStoreParams = null;
        _recordingTypesMap = null;
        _removedFromModel = false;
        _settingsProperty = null;
        _stateSerializer = null;        
        _valueEventSenders = new Hashtable<Settable,String>();
        
        
        for(Recording recording : _piggybacks) {
            recording.setContainer(this);
        }
        
        NamedObj container = getContainer();
        if(container != null)
        {
            _changeEventSenders.add(container);
        }    
       
        Map<String,String> settingsMap = getSettingsMap();
        
        String defaultValue;
        
        String name = "Record Token Values";
        _plParams.add(name);
        if(recordTokens == null) {
            recordTokens = new Parameter(this, name); 
            defaultValue = settingsMap.get(name);
            recordTokens.setToken(new BooleanToken(defaultValue));
            recordTokens.setTypeEquals(BaseType.BOOLEAN);
            recordTokens.setVisibility(Settable.EXPERT);
        }
        
        name = "User Name";
        _plParams.add(name);
        if(username == null) {
            username = new StringParameter(this, name);
            username.setVisibility(Settable.EXPERT);
        }

        name = "Machine Name";
        _plParams.add(name);
        if(hostname == null) {
            hostname = new StringParameter(this, name);
            hostname.setVisibility(Settable.EXPERT);
        }
        
        name = "containerWorkflowLSID";
        _plParams.add(name);
        if(containerWorkflowLSID == null) {
            containerWorkflowLSID = new StringParameter(this, name);
            containerWorkflowLSID.setVisibility(Settable.EXPERT);
        }
        
        name = "containerWorkflowName";
        _plParams.add(name);      
        if(containerWorkflowName == null) {
            containerWorkflowName = new StringParameter(this, name);
            containerWorkflowName.setVisibility(Settable.EXPERT);
        }
       
        name = "Delay Recording Specification";
        _plParams.add(name);
        if(delayRecordingSpecification == null) {
            delayRecordingSpecification = new Parameter(this, name,
                BooleanToken.getInstance(_delayRecordingSpecificationVal));
            delayRecordingSpecification.setTypeEquals(BaseType.BOOLEAN);
            delayRecordingSpecification.setVisibility(Settable.EXPERT);
        }
        
        // set the recording type.
        // NOTE: when the recording type changes, the new recording
        // is told about some of the parameters, such as user name
        // and machine name. These parameters therefore must be
        // created, so we change the recording type last.
        //
        // NOTE: add the recording type to the prov recorders
        // parameters before we set the default recording type;
        // otherwise it will get removed.
        //
        name = _RECORDING_TYPE;
        _plParams.add(name);
        boolean isClone = false;
        if(recordingType == null) {
            recordingType = new StringParameter(this, name);
            isClone = true;
        }
 
        // NOTE: we must load the recording types before we set the default
        // recording type.
        loadRecordingTypes();

        // NOTE: if this ProvenanceRecorder is a clone, then we do
        // not want to set the recording type to the default value.
        // instead, call _changeRecordingType() to instantiate the
        // provStore to the type specified by the original
        // ProvenanceRecorder's recording type.
        if(isClone) {
            defaultValue = settingsMap.get(name);        
            recordingType.setToken(new StringToken(defaultValue));
        } else {
            _changeRecordingType();
        }
        
        // set any remaining default settings.
        for(Map.Entry<String,String> entry : settingsMap.entrySet())
        {
            name = entry.getKey();
            if(!_plParams.contains(name))
            {
                Parameter parameter = (Parameter)getAttribute(name);
                if(parameter != null)
                {
                    parameter.setExpression(entry.getValue());
                    _provStore.attributeChanged(parameter);
                }
            }
        }

        /* not implemented yet...
        recordSshData = new Parameter(this, "Record Ssh System Data",
            new BooleanToken(_recordSshDataVal));
        recordSshData.setTypeEquals(BaseType.BOOLEAN);
        */
        
        _recorders.add(new WeakReference<ProvenanceRecorder>(this));
    }

    /** Add valid recording type choices to the recording types parameter
     *  drop-down box. 
     */
    private void _populateChoices()
    {
        recordingType.removeAllChoices();

        // add the types to the drop-down box
        for(String name : _recordingTypesMap.keySet())
        {
            //_Debug("adding recording type choice " + (String)name);
            recordingType.addChoice(name);
        }

        //Exception e = new Exception();
        //e.printStackTrace();
    }
    
    /** Output the model contents */ 
    private void _recordContainerContents(NamedObj namedObj)
        throws RecordingException
    {
        // whether to recurse based on Recording register method.
        boolean recurse = true;
        
        if(namedObj instanceof Actor)
        {
            if(namedObj instanceof MultiInstanceComposite)
            {
                MultiInstanceComposite mic = (MultiInstanceComposite)namedObj;
                
                // see if it's the master
                // XXX this seems fragile
                if(mic.instance.getExpression().equals("0"))
                {
                    _multiInstanceCompositeMasterNames.add(mic.getName(getContainer()));   
                }
                else
                {
                    _multiInstanceCompositeClones.add(mic);
                }
            }
                        
            recurse = _provStore.regActor((Actor)namedObj);
            
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.regActor((Actor)namedObj);
            }

            _addDebugEventSender(namedObj);
        }
        else if(namedObj instanceof Director)
        {
            recurse = _provStore.regDirector((Director)namedObj);
            
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.regDirector((Director)namedObj);
            }
            
            _addDebugEventSender(namedObj);
        }
        else if(namedObj instanceof TypedIOPort)
        {
            TypedIOPort port = (TypedIOPort)namedObj;
            _provStore.regPort(port);
            
            // do not record information about attributes contained by the port
            recurse = false;
            
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.regPort(port);
            }

            // only listen to opaque ports; transparent ones do not
            // send events.
            if(port.isOpaque())
            {
                _addIOPortEventSender(port);
            }

            /*
            // if the port is an output port or transparent input, add all
            // outgoing connections to portConnTable.
            if(port.isOutput() || !port.isOpaque())
            {
                List tablePorts = new LinkedList<IOPort>();

                List connPorts = null;
                if(port.isOutput())
                {
                    connPorts = port.connectedPortList();
                }
                else
                {
                    connPorts = port.insidePortList();
                }

                Iterator iter = connPorts.iterator();
                while(iter.hasNext())
                {
                    IOPort conn = (IOPort)iter.next();
                    //if(!conn.isOpaque() || !port.isOpaque())
                    //{
                        tablePorts.add(conn);
                    //}
                }
                if(tablePorts.size() > 0)
                {
                    _Debug("table rcver " + port.getFullName() + " -> " + 
                        tablePorts);
                    _portConnTable.put(port, tablePorts);
                }
            }
            */
        }
        else if(namedObj instanceof IORelation)
        {
            IORelation rel = (IORelation)namedObj;
            recurse = _provStore.regRelation(rel);
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.regRelation(rel);
            }
        }
        else if(namedObj != this &&
            // NOTE: do not register a connected port parameter as a parameter
            // since during execution, reading a token by the port generates
            // both port and value change events. value change events are
            // treated as a workflow evolution, which can be expensive.
            (!(namedObj instanceof PortParameter) || 
            ((PortParameter)namedObj).getPort().numberOfSources() == 0))
        {
            recurse = _provStore.regParameter(namedObj);
            
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.regParameter(namedObj);
            }

            // listen for changes in value for certain kinds
            // of settables.
            if(namedObj instanceof Settable &&
                !(namedObj instanceof ColorAttribute) &&
                !(namedObj instanceof SizeAttribute) &&
                !(namedObj instanceof WindowPropertiesAttribute) &&
                !(namedObj instanceof SemanticType) &&
                !(namedObj instanceof ExpertParameter) &&
                !(namedObj instanceof SharedParameter))
            {
                //_Debug("add value listener for " + namedObj.getFullName());
                _updateValueEventSender((Settable)namedObj, true);
                
                /*
                if(namedObj.getFullName().
                    equals(".dataturbine.DataTurbine._icon.text.text"))
                    _Debug("FOUND dataturbine");
                */
            }
        }
        else // namedObj == this
        {
            // do not recurse into our parameters
            recurse = false;
        }

        // see if this namedObj fires
        if(namedObj instanceof FiringsRecordable)
        {
            _addFiringEventSender((FiringsRecordable)namedObj);
        }

        if(recurse)
        {
            // recursively register contents of the current namedObj
            List<NamedObj> contentsList = new LinkedList<NamedObj>();

            boolean isPLOpaque = false;

            if(namedObj instanceof CompositeEntity)
            {
                CompositeEntity composite = (CompositeEntity)namedObj;
                contentsList.addAll(composite.entityList());

                // NOTE: we add the relations last since for each one,
                // regLink() is called and both ends of the link must be
                // registered first.
                contentsList.addAll(composite.relationList());

                // check to see if named obj contains an instance of
                // provenance listener
                List<?> provs = namedObj.attributeList(ProvenanceRecorder.class);
                if(provs != null && provs.size() > 0 && namedObj != getContainer())
                {
                    isPLOpaque = true;
                }
                else if((namedObj instanceof CompositeActor) &&
                    !containsSupportedDirector((CompositeActor)namedObj))
                {
                    isPLOpaque = true;
                }
                
                if(isPLOpaque)
                {
                    _provOpaqueSet.add((CompositeActor)namedObj);                    
                }
            }

            // add the ports to the beginning
            if(namedObj instanceof Entity)
            {
                contentsList.addAll(0, ((Entity<?>)namedObj).portList());
            }

            // add the attributes to the beginning
            contentsList.addAll(0, namedObj.attributeList());

            for(NamedObj containedNamedObj : contentsList)
            {
                if(isPLOpaque &&
                    // do not record contents of these types of objects:
                    ((containedNamedObj instanceof Actor) ||
                     (containedNamedObj instanceof Director) ||
                     (containedNamedObj instanceof IORelation) ||
                     (containedNamedObj instanceof TextAttribute) ||
                     (containedNamedObj instanceof ProvenanceRecorder) ||
                     (containedNamedObj instanceof
                        KeplerDocumentationAttribute)))
                {
                    //_Debug("not recursing down " +
                        //containedNamedObj.getFullName());
                }
                else
                {
                    _recordContainerContents(containedNamedObj);
                }
            }

            // now that all the ports and relations have been registered
            // (if namedObj is a CompositeEntity), it is safe to register
            // the links (since each end point must already registered).

            if(!isPLOpaque && (namedObj instanceof CompositeEntity))
            {
                // iterate over the contained relations
                List<?> relationList = ((CompositeEntity)namedObj).relationList();
                Iterator<?> relationIter = relationList.iterator();
                while(relationIter.hasNext())
                {
                    Relation curRelation = (Relation)relationIter.next();

                    ///if(!adding)
                    //{
                        //containedName = oldName + "." +
                            //curRelation.getName();
                    //}
                    _recordLinksInRelation(curRelation);
                }
            }
        }
    }

    /** Record all the links within a relation. */
    private void _recordLinksInRelation(Relation relation)
        throws RecordingException
    {
        // iterate over the object linked in the current relation
        List<?> linkedObjList = relation.linkedObjectsList();
        Iterator<?> linkedObjsIter = linkedObjList.iterator();
        while(linkedObjsIter.hasNext())
        {
            NamedObj linkedObj = (NamedObj)linkedObjsIter.next();

            // see if current relation is linked to a port
            if(linkedObj instanceof TypedIOPort)
            {
                 _provStore.regLink(linkedObj, relation);
                 
                 // notify any piggybacks
                 for(Recording recording : _piggybacks)
                 {
                     recording.regLink(linkedObj, relation);
                 }
            }
            // otherwise the link is between two relations.
            // we do not want to register this link twice,
            // e.g., a <--> b and b <--> a
            // so only perform registration if the current
            // relation's name lexigraphically precedes the
            // linked relation's name.
            else if(relation.getName().compareTo(
                    linkedObj.getName()) < 0)
            {
                _provStore.regLink(relation, linkedObj);
                
                // notify any piggybacks
                for(Recording recording : _piggybacks)
                {
                    recording.regLink(relation, linkedObj);
                }
            }
        }
    }

    /** Change the Recording type. */
    private void _changeRecordingType() throws IllegalActionException
    {
        String typeStr = recordingType.getExpression();
            
        //System.out.println("chg rec start: " + _curRecordingTypeStr + ", ps = " + _provStore);

        // see if the type is not null and is different than the
        // current type.
        if(!typeStr.trim().isEmpty() && 
                (_curRecordingTypeStr == null || 
                !typeStr.equals(_curRecordingTypeStr)))
        {
            //System.out.println("chg rec: " + _curRecordingTypeStr + " to " + typeStr);

            // see if it's a valid type.
            if(!_recordingTypesMap.containsKey(typeStr))
            {
                throw new IllegalActionException(this,
                    "Unknown recording type: " + typeStr);
            }

            // stop listening to all events
            //
            // NOTE: if we do not unregister from all entities, we may
            // send the new recording an event from an entity it does
            // not know about. (the new recording may ignore entities
            // not ignored by the old recording).
            _stopListening();

            // create a table of all the Parameters in our container.
            Hashtable<String, Parameter> curParamTable = 
                new Hashtable<String, Parameter>();
            Iterator<?> iter = attributeList().iterator();
            while(iter.hasNext())
            {
                NamedObj no = (NamedObj)iter.next();
                if(no instanceof Parameter)
                {
                    curParamTable.put(no.getName(), (Parameter)no);
                }
            }

            String recordingClassStr = _recordingTypesMap.get(typeStr);

            //_Debug("going to instantiate " + recordingClassStr);

            Object newObj = null;
            try
            {
                // attempt to instantiate the new Recording type.
                Class<?> rec = Class.forName(recordingClassStr);
                newObj = rec.newInstance();
            }
            catch(ClassNotFoundException e)
            {
                throw new IllegalActionException(this,
                    "Could not find recording class: " + recordingClassStr);
            }
            catch(InstantiationException e)
            {
                throw new IllegalActionException(this,
                    "Error instantiating " + recordingClassStr + ": " +
                    e.getMessage());
            }
            catch(IllegalAccessException e)
            {
                throw new IllegalActionException(this,
                    "IllegalActionException: " + e.getMessage());
            }
                
            if(!(newObj instanceof Recording))
            {
                throw new IllegalActionException(this,
                    "Class " + recordingClassStr + 
                    " does not subclass Recording.");
            }

            // disconnect existing prov store
            if(_provStore != null)
            {
                try
                {
                    _provStore.disconnect();
                    
                    // notify any piggybacks
                    for(Recording recording : _piggybacks)
                    {
                        recording.disconnect();
                    }
                }
                catch(RecordingException e)
                {
                    throw new IllegalActionException(this, e, 
                        "Error disconnecting previous recording.");
                }
            }
            _provStore = (Recording)newObj;
            _provStore.setContainer(this);
            
            // notify any piggybacks
            for(Recording recording : _piggybacks)
            {
                recording.setContainer(this);
            }

            try
            {
                // tell the new Recording to generate its parameters
                // and put them in a dummy container.
                NamedObj tmp = new NamedObj(workspace());
                _provStoreParams = _provStore.generateParameters(tmp);

                // remove all our current parameters that are not part of 
                // the new Recording.

                // NOTE: we iterate over a copy of the names instead
                // of directly using the names since some may be removed
                // from the table.
                Set<String> currentParamNames = 
                    new HashSet<String>(curParamTable.keySet());
                for(String str : currentParamNames)
                {
                    if(!_provStoreParams.containsName(str) &&
                        !_plParams.contains(str))
                    {
                        Parameter p = curParamTable.get(str);
                        p.setContainer(null);
                        curParamTable.remove(str);

                        //_Debug("rm param: " + str);
                    }
                }

                // finally add parameters from the new Recording
                // that are not in our container.
                for(String str : _provStoreParams.names())
                {
                    // if not in our container, add it
                    if(!curParamTable.containsKey(str))
                    {
                        //_Debug("add new parameter: " + str);
                        _provStoreParams.replaceContainer(str, this);
                    }
                    else
                    {
                        // is in our container, so replace in
                        // generated table.
                            
                        //XXX type could be different, but type not
                        // set when loading from moml.
                        Parameter p = curParamTable.get(str);
                        _provStoreParams.replaceParameter(str, p);
                        
                        // NOTE: tell the recording that the attributed
                        // changed so that it reads the new value.
                        _provStore.attributeChanged(p);
                            
                        //_Debug("replacing parameter: " + str);
                    }
                }
            }
            catch(NameDuplicationException e)
            {
                throw new IllegalActionException(this, e, "Name duplication.");
            }

            _curRecordingTypeStr = typeStr;
            
            // see if we're enabled.
            if (typeStr.equals(DEFAULT_REC_TYPE_IGNORE))
            {
                _isEnabled = false;
            }
            else
            {
                _isEnabled = true;
            }
            
            for(WeakReference<ProvenanceEnabledListener> listenerRef : _enabledListeners)
            {
                if (listenerRef != null)
                {
                    final ProvenanceEnabledListener listener = listenerRef.get();
                    if(listener != null)
                    {
                        listener.toggle(_isEnabled);
                    }
                }
            }

            // tell recording about user name and machine
            _provStore.attributeChanged(username);
            _provStore.attributeChanged(hostname);
            
            // tell recording about state serializer
            if(_stateSerializer != null)
            {
                _provStore.setStateSerializer(_stateSerializer);
            }
            
            String lsidStr = containerWorkflowLSID.stringValue();
            if(lsidStr.length() > 0)
            {
                try
                {
                    _provStore.setContainerLSID(new KeplerLSID(lsidStr));
                }
                catch(Exception e)
                {
                    throw new IllegalActionException(this, e, "Error creating KeplerLSID");
                }
            }
            _provStore.setContainerName(containerWorkflowName.stringValue());

            // start receiving change events from our container
            _addChangeEventSender(getContainer());

            // set debug writer
            if(_debugWriter != null)
            {
                _provStore.setDebugWriter(_debugWriter);
            }
        }
    }

    /** Record the contents of the workflow. */
    private synchronized void _recordWorkflowContents() 
        throws IllegalActionException
    {
        //_Debug("_recordWorkflowContents() regcontents = " + _provStore.regContents());

        try
        {
            if(_provStore != null &&
                (_provStore.regContents()) || _delayRecordingSpecificationVal)
            {
                //_Debug("regContents true!");
    
                //_portConnTable.clear();
                _provOpaqueSet.clear();
                
                // record workflow specification

                _provStore.specificationStart();
                
                // notify any piggybacks
                for(Recording recording : _piggybacks)
                {
                    recording.specificationStart();
                }
                
                _recordContainerContents(getContainer());
                
                _provStore.specificationStop();
                
                // notify any piggybacks
                for(Recording recording : _piggybacks)
                {
                    recording.specificationStop();
                }
            }
        }
        catch(RecordingException e)
        {
            //e.printStackTrace();
            throw new IllegalActionException(this, e, "Error recording " +
                "workflow structure: " + e.getMessage());
        }
    }
    
    /** Set the name of the provenance recorder using the default name
     *  in the configuration file.
     */
    private void _setDefaultName() throws IllegalActionException, NameDuplicationException
    {
        Map<String,String> settingsMap = getSettingsMap();
        String name = settingsMap.get(_DEFAULT_NAME);
        setName(name);
    }
    
    
    /** Return a Map of the settings, returns default settings if necessary */
    public Map<String,String> getSettingsMap()
    {
        if (_settingsProperty == null)
        {
                return getDefaultsMap();
        }
        else
        {
                return ConfigurationUtilities.getPairsMap(_settingsProperty);
        }
    }
    
    /** Return a Map of the default settings. */
    public static Map<String,String> getDefaultsMap()
    {
        ConfigurationProperty defaultsProperty =
            ConfigurationManager.getInstance().getProperty(
            ConfigurationManager.getModule("provenance"), "provenance.defaultSettings");
        return ConfigurationUtilities.getPairsMap(defaultsProperty);
    }

    /** Listen to a Debuggable, and add to the debug event senders list. */
    private void _addDebugEventSender(Debuggable debuggable)
    {
        debuggable.addDebugListener(this);
        _debugEventSenders.add(debuggable);
    }

    /** Listen to a FiringsRecordable and add to firing event senders list. */
    private void _addFiringEventSender(FiringsRecordable firable)
    {
        firable.addActorFiringListener(this);
        _firingEventSenders.add(firable);
    }

    /** Listen to an IOPort and add to port event senders list. */
    private void _addIOPortEventSender(IOPort port)
    {
        //_Debug("going to listen to " + port.getFullName());
        port.addIOPortEventListener(this);
        _portEventSenders.add(port); 
    }

    /** Start or stop listening to a Settable for value change events. */
    private void _updateValueEventSender(Settable settable, boolean add)
    {
        if(add)
        {
            settable.addValueListener(this);
            if(settable instanceof Variable) {
                ((Variable)settable).setValueListenerAsWeakDependency(this);
            }
            _valueEventSenders.put(settable, ((NamedObj)settable).getFullName());
        }
        else
        {
            settable.removeValueListener(this);
            _valueEventSenders.remove(settable);
        }
    }

    /** Listen to a NamedObj for change events. */
    private void _addChangeEventSender(NamedObj no)
    {
        if(no != null)
        {
            no.addChangeListener(this);
            _changeEventSenders.add(no);
        }
    }

    /** Stop listening to all events. */
    private synchronized void _stopListening()
    {
        // value changes.
        for(Settable settable : _valueEventSenders.keySet())
        {
            settable.removeValueListener(this);
        }
        _valueEventSenders.clear();

    
        // debug events
        for(Debuggable d : _debugEventSenders)
        {
            d.removeDebugListener(this);
        }
        _debugEventSenders.clear();

        // firing events
        for(FiringsRecordable fs : _firingEventSenders)
        {
            fs.removeActorFiringListener(this);
        }
        _firingEventSenders.clear();
    
        // port events
        for(IOPort port : _portEventSenders)
        {
            port.removeIOPortEventListener(this);
        }
        _portEventSenders.clear();
    
        // change events
        for(NamedObj sender : _changeEventSenders) 
        {
            sender.removeChangeListener(this);
        }
        _changeEventSenders.clear();
    }
    
    /** Write to debug writer (if present) and stdout. */
    private void _debugWrite(String message)
    {
        System.out.println(message);
        
        if(_debugWriter != null)
        {
            try
            {
                _debugWriter.write(message + "\n");
            }
            catch (IOException e)
            {
                System.out.println("ERROR writing to debug writer: " +
                    e.getMessage());
            }
        }
    }
    
    ///////////////////////////////////////////////////////////////////
    ////                       private classes                     ////
    
    /** A class to save a reference to a DebugEvent. */
    private static class DelayedEvent
    {
        public DelayedEvent(DebugEvent event, boolean add)
        {
            _event = event;
            _add = add;
        }
        
        public DebugEvent getEvent()
        {
            return _event;
        }
        
        public boolean isAdd()
        {
            return _add;
        }
        
        /** If true, event is an add, otherwise event is a remove. */
        private boolean _add;
        
        /** The event. */
        private DebugEvent _event;
    }
        
    ///////////////////////////////////////////////////////////////////
    ////                       private variables                   ////

    /** Provenance storage. */
    private Recording _provStore = null;

    /** A set of all senders of DebugEvents. */
    private Set<Debuggable> _debugEventSenders = null;
    
    /** A set of all senders of IOPortEvents . */
    private Set<IOPort> _portEventSenders = null;
    
    /** A set of all senders of FiringEvents. */
    private Set<FiringsRecordable> _firingEventSenders = null;

    /** A map of all senders of valueChanged(). When a parameter is
     *  deleted, we may receive a valueChange event and these should
     *  be ignored. The parameter or its container no longer has a
     *  container, so getFullName() returns a different string.
     *  We cache the full name in this map so we can tell when it
     *  has changed. 
     */
    private Map<Settable,String> _valueEventSenders;

    /** A cache of all parameter values. */
    private Map<Settable,String> _paramValueTable = null;

    /** A set of all senders of ChangeEvents. */
    private Set<NamedObj> _changeEventSenders = null;

    /** The following hold Parameter values. */
    //private boolean _recordSshDataVal = false;
    private boolean _recordTokensVal = false;
    //private boolean _recordTransparentPortsVal = true;

    /** Value of delayRecordingSpecification parameter. */
    private boolean _delayRecordingSpecificationVal = true;

    /** A set of parameters used by ProvenanceRecorder. */
    private Set<String> _plParams;

    /** Parameters used by the current recording object. */
    private RecordingParameters _provStoreParams = null;

    /** Currently selected recording type. */
    private String _curRecordingTypeStr = "<unknown>";

    /** Mapping of name to class of valid recording types. */
    private Map<String,String> _recordingTypesMap;
    
    /** A table that maps a port to outgoing connected ports. */
    //private Hashtable<IOPort,List<IOPort>> _portConnTable = null;

    /** A set of composite actors that contain a ProvenanceRecorder instance. 
        Our container is not in the set.
     */
    private Set<CompositeActor> _provOpaqueSet = null;

    /** True if we are listening to execution of manager. */
    private boolean _addedExecutionListener = false;
    
    /** List of objects whose (pre)initialize() and wrapup() methods
     *  should be slaved to these.
     */
    private transient List<Initializable> _initializables;

    /** A collection of attributes whose value has changed, but did
     *  not belong to us. They might belong to the recording type. 
     *  We store them and tell the recording once it has been created.
     */
    private Set<Attribute> _possibleRecordingAttributes;

    /** If true, we have been removed from the model. */
    private boolean _removedFromModel = false;

    /** Used for debugging output. */
    private Writer _debugWriter;
   
    /** If true, have workflow has executed at least once. */
    private boolean _haveExecuted = false;

    /** If true, workflow is executing. */
    private boolean _amExecuting = false;
    
    /** A list of recordings to be notified of provenance events. */
    private transient List<Recording> _piggybacks;
    
    /** A list of recordings to be notified of provenance events for all
     *  newly created ProvenanceRecorders. Only key set in the WeakHashMap
     *  is useful.
     */
    private static transient WeakHashMap<Recording, Object> _futurePiggybacks =
        new WeakHashMap<Recording, Object>();

    /** Settables that we should ignore if additional valueChanged events are
     *  received for them.
     */
    private Set<Settable> _pendingSettables = new HashSet<Settable>();
 
    /** A list of events to process if we are delaying recording
     *  specification. 
     */ 
    private List<DelayedEvent> _delayedEventList;
        
    /** The name of the key in the configuration file for the name of the
     *  default provenance recorder.
     */
    private static final String _DEFAULT_NAME = "Provenance Recorder Name";
    
    private static final String _RECORDING_TYPE = "Recording Type";
    
    private ConfigurationProperty _settingsProperty = null;
    
    /** KeplerLSID for current execution */
    private KeplerLSID _executionLSID = null;
    
    /** True if recording type is not set to IGNORE. */
    private boolean _isEnabled;
    
    /** A list of listeners for enabled events. */
    private List<WeakReference<ProvenanceEnabledListener>> _enabledListeners;
        
    /** A set containing the MultiInstanceComposite clones seen during the
     *  initial recording contents. During initialize(), any clones that
     *  are found but not contained in this set are assumed to have been
     *  created during preinitialize(), and registered.
     */
    private Set<MultiInstanceComposite> _multiInstanceCompositeClones = 
        new HashSet<MultiInstanceComposite>();
    
    /** A set containing names of MultiInstanceComposite masters (non-clones).
     */
    private Set<String> _multiInstanceCompositeMasterNames = 
        new HashSet<String>();
    
    /** A set containing all instances of ProvenanceRecorder. */
    private static Set<WeakReference<ProvenanceRecorder>> _recorders
        = Collections.synchronizedSet(new HashSet<WeakReference<ProvenanceRecorder>>());

    /** Serialize states for recordings. */
    private StateSerializer _stateSerializer;

    private static final Log log = LogFactory.getLog(ProvenanceRecorder.class.getName());
    //private static final boolean isDebugging = log.isDebugEnabled();
}