/* The provenance recording API.

Copyright (c) 2007-2010 The Regents of the University of California.
All rights reserved.
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.IOException;
import java.io.Writer;
import java.net.InetAddress;
import java.net.UnknownHostException;
import java.util.Date;
import java.util.Map;

import org.kepler.objectmanager.lsid.KeplerLSID;
import org.kepler.tagging.TagEvent;
import org.kepler.util.WorkflowRenameListener;

import ptolemy.actor.Actor;
import ptolemy.actor.Director;
import ptolemy.actor.FiringEvent;
import ptolemy.actor.IOPortEvent;
import ptolemy.actor.IORelation;
import ptolemy.actor.TypedIOPort;
import ptolemy.data.StringToken;
import ptolemy.data.expr.Parameter;
import ptolemy.kernel.util.Attribute;
import ptolemy.kernel.util.IllegalActionException;
import ptolemy.kernel.util.NameDuplicationException;
import ptolemy.kernel.util.Nameable;
import ptolemy.kernel.util.NamedObj;

/** The provenance recorder uses the API provided by this class to
 * write provenance information. This base class does not store the
 * provenance data, but should be sub-classed to record it to a specific
 * medium. For examples, see SQLRecording, and TextFileRecording. 
 * 
 * The API roughly consists of three parts: specification, evolution,
 * and execution.
 * 
 * <p> The workflow structure, or <em>specification</em>, is recorded
 * using the regNNN() methods. specificationStart() and specificationStop()
 * are called before and after workflow structure is recorded. 
 * </p>
 * <p>
 * FIXME this is not all implemented
 * An <em>evolution</em> is a group of changes to the workflow structure.
 * evolutionStart() and evolutionStop() are called before and after
 * each change or group of changes to the workflow. A change
 * may be one of:
 * <ul>
 * <li>Addition to the workflow: the corresponding regNNN() method in
 * the <i>Specification</i> interface is called.</li>
 * <li>Removal from the workflow: the remove() or removeLink() method in
 * this interface is called.</li>
 * <li>Rename a NamedObj in the workflow: 
 * <li>Parameter value change: regParameter() in <i>Specification</i>
 * is called.</li>
 * </ul>
 * </p>
 * <p>
 * When a workflow <em>executes</em>, methods are called for actors firing,
 * ports reading and writing, and if an error occurs. executionStart() and
 * executionStop() are called before and after execution.
 * </p>
 *
 * @author Daniel Crawl
 * @version $Id: Recording.java 33385 2015-05-01 03:05:27Z crawl $
 *
 */
    
public class Recording
{

    /** Create a new provenance recording. */
    public Recording() throws RecordingException
    {
    }

    /** Stop recording. Called when the Recording type changes
     *  or the provenance recorder is removed from canvas. 
     *  NOTE: this is NOT called when the GUI exits or when the
     *  workflow runs from the command line.
     *  
     *  This is the last method called to a Recording instance.
     */
    public void disconnect() throws RecordingException
    {
    }

    // Specification
    
    /** Called before registering workflow contents. */
    public void specificationStart() throws RecordingException
    {
        // by default, we only want the contents registered once.
        // NOTE: we change _needWorkflowContents to false here
        // instead of specificationStop() since regContents()
        // may be called in the process of the ProvenanceRecorder
        // registering workflow contents.
        _needWorkflowContents = false; 

        //_debug("spec stop needWorkflowContents = false");
    }

    /** Called when finished registering workflow contents. */
    public void specificationStop() throws RecordingException
    {
    }

    /** Returns true if provenance recorder should register workflow
     *  contents should be registered. 
     */
    public boolean regContents() throws RecordingException
    {
        return _needWorkflowContents;
    }

    /** Register an actor. 
     *
     * @return if true, register contents of actor.
     */
    public boolean regActor(Actor actor) throws RecordingException
    {
        return false;
    }

    /** Register a director. 
     * 
     * @return if true, register contents of director.
     */
    public boolean regDirector(Director director) throws RecordingException
    {
        return false; 
    }

    /** Register a parameter. A parameter can be anything
     * stored in the MoML that does not have its own
     * <code>regNNN()</code> method. This can be user-level 
     * parameters (e.g., Parameter, StringParameter, etc.) or
     * internal to Kepler (e.g., _location, semanticType000, etc.).
     * (A "parameter" corresponds to a property in the MoML).
     *
     * @return if true, register contents of parameter.
     */
    public boolean regParameter(NamedObj parameter) throws RecordingException
    {
        return false; 
    }

    /** Register a link between two endpoints. Each endpoint must already
     * be registered as a port or relation. NOTE: in ptII, a link can 
     * between a port and a relation, or between two relations.
     *
     * @param endPoint1 first endpoint.
     * @param endPoint2 second endpoint.
     * @return if true, register contents of link.
     */
    public boolean regLink(NamedObj endPoint1, NamedObj endPoint2)
        throws RecordingException
    {
        return false; 
    }

    /** Register a port or portparameter.
     *
     * @return if true, register contents of port.
     */
    public boolean regPort(TypedIOPort port) throws RecordingException
    {
        return false; 
    }

    /** Register a relation.
     *
     * @return if true, register contents of relation.
     */
    public boolean regRelation(IORelation relation) throws RecordingException
    {
        return false; 
    }

    // Evolution
   
    /** Start an evolution. */
    public void evolutionStart() throws RecordingException
    {
            
    }
    
    /** Stop an evolution. */
    public void evolutionStop() throws RecordingException
    {
            
    }

    /** A NamedObj was removed. */
    public void remove(String name) throws RecordingException
    {
         
    }

    /** Remove a link between two endpoints. Links do not have names
     *  (they are not NamedObjs, so remove() cannot be used.
     */
    public void removeLink(String endPoint1, String endPoint2)
        throws RecordingException
    {

    }
    
    /** A NamedObj was renamed. */
    public void rename(String oldName, String newName) 
        throws RecordingException
    {
            
    }

    // Execution of workflow
    
  
    /** Record the starting of workflow execution. */
    public void executionStart() throws RecordingException
    {
        
    }
    
    /** Record the starting of workflow execution at a specific time. */
    public void executionStart(Date timestamp) throws RecordingException
    {
        executionStart();
    }
    
    /**
     * Record the starting of workflow execution.
     * @param executionLSID
     * @throws RecordingException
     */
        public void executionStart(KeplerLSID executionLSID) 
                throws RecordingException
        {
                executionStart();
        }

    /**
     * Record the starting of workflow execution at a specific time.
     * @param executionLSID
     * @throws RecordingException
     */
    public void executionStart(KeplerLSID executionLSID, Date timestamp) 
        throws RecordingException
    {
        executionStart(executionLSID);
    }

    /** Record the stopping of workflow execution. */
    public void executionStop() throws RecordingException
    {
        
    }

    /** Record the stopping of workflow execution at a specific time. */
    public void executionStop(Date timestamp) throws RecordingException
    {
        executionStop();
    }

    /**
     * Record the stopping of workflow execution.
     * @param executionLSID
     * @throws RecordingException
     */
        public void executionStop(KeplerLSID executionLSID) 
                throws RecordingException
        {
                executionStop();
        }

    /**
     * Record the stopping of workflow execution.
     * @param executionLSID
     * @throws RecordingException
     */
    public void executionStop(KeplerLSID executionLSID, Date timestamp) 
        throws RecordingException
    {
        executionStop(executionLSID);
    }

    /** An execution was imported. */
        public void executionImported() 
        {
        }
        
    /** An execution was imported. */
        public void executionImported(KeplerLSID executionLSID) 
        {
                executionImported();
        }
    
    /** An actor threw an exception.
    *
    * @param source the source of the error. This may be null.
    * @param throwable the error.
    */
    public void executionError(Nameable source, Throwable throwable)
        throws RecordingException
    {

    }
    
    /**
     * An actor threw an exception.
     * @param source
     * @param throwable
     * @param executionLSID
     * @throws RecordingException
     */
        public void executionError(Nameable source, Throwable throwable,
                        KeplerLSID executionLSID) throws RecordingException
        {
                executionError(source, throwable);
        }
    
    /** Associate the contents of a file with the most recent workflow execution. */
    public void addFileForLastExecution(Map<String,String> metadataMap, File file) 
        throws RecordingException
    {
        
    }

    /** Record an actor firing at the current time. */
    public void actorFire(FiringEvent event) throws RecordingException
    {
        actorFire(event, new Date());
    }
    
    /** Record an actor firing at a specific time. */
    public void actorFire(FiringEvent event, Date timestamp) throws RecordingException
    {
        
    }

    /** Record a port event at the current time. */
    public void portEvent(IOPortEvent event) throws RecordingException
    {
        portEvent(event, new Date());
    }

    /** Record a port event at a specific time. */
    public void portEvent(IOPortEvent event, Date timestamp) throws RecordingException
    {
        
    }

    /** Record a port event. Data contained in a token can be
     * retrieved using Token.toString(). Application-specific
     * token types must implement this method to serialize data.
     */
    public void refillPortEvent(IOPortRefillEvent event) throws RecordingException
    {
        
    }

    /** Record a custom provenance event. */
    public void customProvEvent(ProvenanceEvent event) throws RecordingException
    {
        
    }

    /** Add Parameters to ProvenanceListener configuration GUI. */
    public RecordingParameters generateParameters(NamedObj no) 
        throws IllegalActionException, NameDuplicationException
    {
        return new RecordingParameters(no);
    }

    /** React to a change in an attribute. */
    public void attributeChanged(Attribute attribute)
        throws IllegalActionException
    {
        //_debug("Recording.attributeChanged: " + attribute);

        if(attribute.getName().equals("Machine Name"))
        {
            _machineStr = 
                ((StringToken)((Parameter)attribute).getToken()).stringValue();
            
            if(_machineStr.length() == 0)
            {
                // try to set default from InetAddress
                try
                {
                    InetAddress addr = InetAddress.getLocalHost();
                    _machineStr = addr.getHostName();
                }
                catch(UnknownHostException e)
                {
                    _machineStr = "127.0.0.1";
                }
            }
        }
    }

    /** Get a Queryable connected to the Recording output.
     *  @exception QueryException may be thrown if Queryable not implemented
     *  for the Recording type.
     * @throws RecordingException 
     */
    public Queryable getQueryable(boolean allowReconnectWF) throws QueryException, RecordingException
    {
        throw new QueryException("Queryable for recording " +
                getClass().getName() + " is not implemented.");
    }
    
    /** Get the container. */
    public ProvenanceRecorder getContainer() {
        return _recorder;
    }
    
    /** Set the container. */
    public void setContainer(ProvenanceRecorder container)
    {
        if(container == null)
        {
                _recorderContainer = null;
        }
        else
        {
                _recorderContainer = container.getContainer();
        }
        _updateContainerName();
    }
   
    /** Set a Writer for debugging output. */
    public void setDebugWriter(Writer writer)
    {
        _debugWriter = writer;
    }
    
    /** Set the container LSID. This is used when a sub workflow is
     *  ran separately at the top level.
     */
    public void setContainerLSID(KeplerLSID lsid)
    {
        _containerLSID = lsid;
    }
    
    /** Set the container name. This is used when a sub workflow is
     *  ran separately at the top level.
     */
    public void setContainerName(String name)
    {
        _containerName = name;
    }
 
    /** 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
     * @throws RecordingException 
     * @see WorkflowRenameListener
     */
    public void renamedWorkflow(NamedObj namedObj, KeplerLSID oldLSID,
        KeplerLSID newLSID, String oldName, String newName) throws RecordingException
    {
        
    }
    
    /* A tag was added. */
    public void tagAdded(TagEvent event) throws RecordingException
    {
        
    }
    
    /* A tag was removed. */
    public void tagRemoved(TagEvent event) throws RecordingException
    {
        
    }

        /**
         * Change execution LSID for an execution Id. Does not change and returns
         * false for attempts to change to an older or current revision, or if a
         * QueryException, or if no such execution Id.
         * 
         * @param execId
         * @param newExecLSID
         * @return
         * @throws RecordingException
         */
        public boolean changeExecutionLSID(int execId, KeplerLSID newExecLSID,
                        Queryable q) throws RecordingException 
        {
                return false;
        }
    
    /** Delete a list of workflow executions by lsid
     * @return numRowsDeleted
     */
    //public int deleteExecutions(List<KeplerLSID> lsids) throws RecordingException{
    //  return 0;
    //}
    
    /** Set the state serializer. */
    public void setStateSerializer(StateSerializer serializer)
    {
        _stateSerializer = serializer;
    }
    
    /** Remove the state serializer. */
    public void removeStateSerializer()
    {
        _stateSerializer = null;
    }
    
    ////////////////////////////////////////////////////////////////////////
    //// protected methods                                              ////

    /** Debugging output. */
    protected void _debug(String str)
    {
        if(_debugPrint)
        {
            System.out.println("DEBUG: " + str);
            System.out.flush();
        }
    }

    /** Debugging output. */
    protected void _debug(Object object)
    {
        _debug(object.toString());
    }

    /** Warning output. */
    protected void _warn(String str)
    {
        System.out.println("WARNING: " + str);
        System.out.flush();
    }

    /** Error output. */
    protected void _error(String str)
    {
        System.out.println("ERROR: " + str);
        System.out.flush();
    }

    protected String _getExceptionMessage(Exception e)
    {
        e.printStackTrace();
        return e.getClass().getName() + ": " + e.getMessage();
    }

    /** Write to any debug writer. */
    protected void _debugWrite(String str) throws RecordingException
    {
        if(_debugWriter != null)
        {
            try
            {
                _debugWriter.write(str);
                _debugWriter.write("\n");
            }
            catch(IOException e)
            {
                throw new RecordingException("Error writing to debug writer:",
                    e);
            }
        }
    }

    /** Write to any debug writer. */
    protected void _debugWrite(String str, Throwable t)
        throws RecordingException
    {
        _debugWrite(str + t.getMessage());
    }

    /** Set the value for needing workflow contents to be registered. */
    protected void _needWorkflowContents(boolean val)
    {
        _needWorkflowContents = val;
        //_debug("needWorkflowContents changed to " + _needWorkflowContents);
    }
   
    /** Update the container's name. */
    protected void _updateContainerName()
    {
        if(_recorderContainer == null)
        {
            _containerFullName = null;
        }
        else
        {
            _containerFullName = _getNameableFullName(_recorderContainer);
        }
    }

    /** Get a Nameable's full name including the name of the containing
     *  workflow.
     */
    protected String _getNameableFullName(Nameable nameable)
    {
        if(_containerName != null)
        {
            return _containerName + nameable.getFullName();
        }
        else
        {
            return nameable.getFullName();
        }
    }

    ////////////////////////////////////////////////////////////////////////
    //// protected variables                                            ////

    /** The full name of the provenance recorder's container. */
    protected String _containerFullName;

    /** If true, output debugging statements to stdout. */
    protected boolean _debugPrint = true;

    /** Used for debugging output. */
    protected Writer _debugWriter;

    /** The machine name */
    protected String _machineStr = "unknown";

    /** The container of the provenance recorder. */
    protected NamedObj _recorderContainer;
    
    /** The containing provenance recorder. */
    protected ProvenanceRecorder _recorder;
    
    /** The LSID of the containing workflow. */
    protected KeplerLSID _containerLSID;
    
    /** The name of the containing workflow. */
    protected String _containerName = null;
    
    /** A serializer for states. */
    protected StateSerializer _stateSerializer;
    
    ////////////////////////////////////////////////////////////////////////
    //// private variables                                              ////

    /** If provenance recorder should register workflow contents. */
    private boolean _needWorkflowContents = false;
}