org.kepler.provenance

Class Recording

java.lang.Object

org.kepler.provenance.Recording

Direct Known Subclasses:

OpenProvenanceModelXML, SimpleFiringRecording, SQLRecording, TextFileRecording, WorkflowRunManagerRecording, XMLRecording

public class Recording
extends java.lang.Object

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.

The workflow structure, or specification, is recorded using the regNNN() methods. specificationStart() and specificationStop() are called before and after workflow structure is recorded.

FIXME this is not all implemented An evolution 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:

• Addition to the workflow: the corresponding regNNN() method in the Specification interface is called.
• Removal from the workflow: the remove() or removeLink() method in this interface is called.
• Rename a NamedObj in the workflow:
• Parameter value change: regParameter() in Specification is called.

When a workflow executes, methods are called for actors firing, ports reading and writing, and if an error occurs. executionStart() and executionStop() are called before and after execution.

Author:

Daniel Crawl

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	_containerFullName The full name of the provenance recorder's container.
protected KeplerLSID	_containerLSID The LSID of the containing workflow.
protected java.lang.String	_containerName The name of the containing workflow.
protected boolean	_debugPrint If true, output debugging statements to stdout.
protected java.io.Writer	_debugWriter Used for debugging output.
protected java.lang.String	_machineStr The machine name
protected ProvenanceRecorder	_recorder The containing provenance recorder.
protected NamedObj	_recorderContainer The container of the provenance recorder.
protected StateSerializer	_stateSerializer A serializer for states.

Constructor Summary

Constructors

Constructor and Description
Recording() Create a new provenance recording.

Method Summary

Modifier and Type	Method and Description
protected void	_debug(java.lang.Object object) Debugging output.
protected void	_debug(java.lang.String str) Debugging output.
protected void	_debugWrite(java.lang.String str) Write to any debug writer.
protected void	_debugWrite(java.lang.String str, java.lang.Throwable t) Write to any debug writer.
protected void	_error(java.lang.String str) Error output.
protected java.lang.String	_getExceptionMessage(java.lang.Exception e)
protected java.lang.String	_getNameableFullName(Nameable nameable) Get a Nameable's full name including the name of the containing workflow.
protected void	_needWorkflowContents(boolean val) Set the value for needing workflow contents to be registered.
protected void	_updateContainerName() Update the container's name.
protected void	_warn(java.lang.String str) Warning output.
void	actorFire(FiringEvent event) Record an actor firing at the current time.
void	actorFire(FiringEvent event, java.util.Date timestamp) Record an actor firing at a specific time.
void	addFileForLastExecution(java.util.Map<java.lang.String,java.lang.String> metadataMap, java.io.File file) Associate the contents of a file with the most recent workflow execution.
void	attributeChanged(Attribute attribute) React to a change in an attribute.
boolean	changeExecutionLSID(int execId, KeplerLSID newExecLSID, Queryable q) Change execution LSID for an execution Id.
void	customProvEvent(ProvenanceEvent event) Record a custom provenance event.
void	disconnect() Stop recording.
void	evolutionStart() Start an evolution.
void	evolutionStop() Stop an evolution.
void	executionError(Nameable source, java.lang.Throwable throwable) An actor threw an exception.
void	executionError(Nameable source, java.lang.Throwable throwable, KeplerLSID executionLSID) An actor threw an exception.
void	executionImported() An execution was imported.
void	executionImported(KeplerLSID executionLSID) An execution was imported.
void	executionStart() Record the starting of workflow execution.
void	executionStart(java.util.Date timestamp) Record the starting of workflow execution at a specific time.
void	executionStart(KeplerLSID executionLSID) Record the starting of workflow execution.
void	executionStart(KeplerLSID executionLSID, java.util.Date timestamp) Record the starting of workflow execution at a specific time.
void	executionStop() Record the stopping of workflow execution.
void	executionStop(java.util.Date timestamp) Record the stopping of workflow execution at a specific time.
void	executionStop(KeplerLSID executionLSID) Record the stopping of workflow execution.
void	executionStop(KeplerLSID executionLSID, java.util.Date timestamp) Record the stopping of workflow execution.
RecordingParameters	generateParameters(NamedObj no) Add Parameters to ProvenanceListener configuration GUI.
ProvenanceRecorder	getContainer() Get the container.
Queryable	getQueryable(boolean allowReconnectWF) Get a Queryable connected to the Recording output.
void	portEvent(IOPortEvent event) Record a port event at the current time.
void	portEvent(IOPortEvent event, java.util.Date timestamp) Record a port event at a specific time.
void	refillPortEvent(IOPortRefillEvent event) Record a port event.
boolean	regActor(Actor actor) Register an actor.
boolean	regContents() Returns true if provenance recorder should register workflow contents should be registered.
boolean	regDirector(Director director) Register a director.
boolean	regLink(NamedObj endPoint1, NamedObj endPoint2) Register a link between two endpoints.
boolean	regParameter(NamedObj parameter) Register a parameter.
boolean	regPort(TypedIOPort port) Register a port or portparameter.
boolean	regRelation(IORelation relation) Register a relation.
void	remove(java.lang.String name) A NamedObj was removed.
void	removeLink(java.lang.String endPoint1, java.lang.String endPoint2) Remove a link between two endpoints.
void	removeStateSerializer() Remove the state serializer.
void	rename(java.lang.String oldName, java.lang.String newName) A NamedObj was renamed.
void	renamedWorkflow(NamedObj namedObj, KeplerLSID oldLSID, KeplerLSID newLSID, java.lang.String oldName, java.lang.String newName) A workflow was renamed.
void	setContainer(ProvenanceRecorder container) Set the container.
void	setContainerLSID(KeplerLSID lsid) Set the container LSID.
void	setContainerName(java.lang.String name) Set the container name.
void	setDebugWriter(java.io.Writer writer) Set a Writer for debugging output.
void	setStateSerializer(StateSerializer serializer) Set the state serializer.
void	specificationStart() Called before registering workflow contents.
void	specificationStop() Called when finished registering workflow contents.
void	tagAdded(TagEvent event)
void	tagRemoved(TagEvent event)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_containerFullName

protected java.lang.String _containerFullName

The full name of the provenance recorder's container.

_debugPrint

protected boolean _debugPrint

If true, output debugging statements to stdout.

_debugWriter

protected java.io.Writer _debugWriter

Used for debugging output.

_machineStr

protected java.lang.String _machineStr

The machine name

_recorderContainer

protected NamedObj _recorderContainer

The container of the provenance recorder.

_recorder

protected ProvenanceRecorder _recorder

The containing provenance recorder.

_containerLSID

protected KeplerLSID _containerLSID

The LSID of the containing workflow.

_containerName

protected java.lang.String _containerName

The name of the containing workflow.

_stateSerializer

protected StateSerializer _stateSerializer

A serializer for states.

Constructor Detail

Recording

public Recording()
          throws RecordingException

Create a new provenance recording.

Throws:

RecordingException

Method Detail

disconnect

public void disconnect()
                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.

Throws:

RecordingException

specificationStart

public void specificationStart()
                        throws RecordingException

Called before registering workflow contents.

Throws:

RecordingException

specificationStop

public void specificationStop()
                       throws RecordingException

Called when finished registering workflow contents.

Throws:

RecordingException

regContents

public boolean regContents()
                    throws RecordingException

Returns true if provenance recorder should register workflow contents should be registered.

Throws:

RecordingException

regActor

public boolean regActor(Actor actor)
                 throws RecordingException

Register an actor.

Returns:

if true, register contents of actor.

Throws:

RecordingException

regDirector

public boolean regDirector(Director director)
                    throws RecordingException

Register a director.

Returns:

if true, register contents of director.

Throws:

RecordingException

regParameter

public boolean regParameter(NamedObj parameter)
                     throws RecordingException

Register a parameter. A parameter can be anything stored in the MoML that does not have its own regNNN() 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).

Returns:

if true, register contents of parameter.

Throws:

RecordingException

regLink

public boolean regLink(NamedObj endPoint1,
                       NamedObj endPoint2)
                throws RecordingException

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.

Parameters:

endPoint1 - first endpoint.

endPoint2 - second endpoint.

Returns:

if true, register contents of link.

Throws:

RecordingException

regPort

public boolean regPort(TypedIOPort port)
                throws RecordingException

Register a port or portparameter.

Returns:

if true, register contents of port.

Throws:

RecordingException

regRelation

public boolean regRelation(IORelation relation)
                    throws RecordingException

Register a relation.

Returns:

if true, register contents of relation.

Throws:

RecordingException

evolutionStart

public void evolutionStart()
                    throws RecordingException

Start an evolution.

Throws:

RecordingException

evolutionStop

public void evolutionStop()
                   throws RecordingException

Stop an evolution.

Throws:

RecordingException

remove

public void remove(java.lang.String name)
            throws RecordingException

A NamedObj was removed.

Throws:

RecordingException

removeLink

public void removeLink(java.lang.String endPoint1,
                       java.lang.String endPoint2)
                throws RecordingException

Remove a link between two endpoints. Links do not have names (they are not NamedObjs, so remove() cannot be used.

Throws:

RecordingException

rename

public void rename(java.lang.String oldName,
                   java.lang.String newName)
            throws RecordingException

A NamedObj was renamed.

Throws:

RecordingException

executionStart

public void executionStart()
                    throws RecordingException

Record the starting of workflow execution.

Throws:

RecordingException

executionStart

public void executionStart(java.util.Date timestamp)
                    throws RecordingException

Record the starting of workflow execution at a specific time.

Throws:

RecordingException

executionStart

public void executionStart(KeplerLSID executionLSID)
                    throws RecordingException

Record the starting of workflow execution.

Parameters:

executionLSID -

Throws:

RecordingException

executionStart

public void executionStart(KeplerLSID executionLSID,
                           java.util.Date timestamp)
                    throws RecordingException

Record the starting of workflow execution at a specific time.

Parameters:

executionLSID -

Throws:

RecordingException

executionStop

public void executionStop()
                   throws RecordingException

Record the stopping of workflow execution.

Throws:

RecordingException

executionStop

public void executionStop(java.util.Date timestamp)
                   throws RecordingException

Record the stopping of workflow execution at a specific time.

Throws:

RecordingException

executionStop

public void executionStop(KeplerLSID executionLSID)
                   throws RecordingException

Record the stopping of workflow execution.

Parameters:

executionLSID -

Throws:

RecordingException

executionStop

public void executionStop(KeplerLSID executionLSID,
                          java.util.Date timestamp)
                   throws RecordingException

Record the stopping of workflow execution.

Parameters:

executionLSID -

Throws:

RecordingException

executionImported

public void executionImported()

An execution was imported.

executionImported

public void executionImported(KeplerLSID executionLSID)

An execution was imported.

executionError

public void executionError(Nameable source,
                           java.lang.Throwable throwable)
                    throws RecordingException

An actor threw an exception.

Parameters:

source - the source of the error. This may be null.

throwable - the error.

Throws:

RecordingException

executionError

public void executionError(Nameable source,
                           java.lang.Throwable throwable,
                           KeplerLSID executionLSID)
                    throws RecordingException

An actor threw an exception.

Parameters:

source -

throwable -

executionLSID -

Throws:

RecordingException

addFileForLastExecution

public void addFileForLastExecution(java.util.Map<java.lang.String,java.lang.String> metadataMap,
                                    java.io.File file)
                             throws RecordingException

Associate the contents of a file with the most recent workflow execution.

Throws:

RecordingException

actorFire

public void actorFire(FiringEvent event)
               throws RecordingException

Record an actor firing at the current time.

Throws:

RecordingException

actorFire

public void actorFire(FiringEvent event,
                      java.util.Date timestamp)
               throws RecordingException

Record an actor firing at a specific time.

Throws:

RecordingException

portEvent

public void portEvent(IOPortEvent event)
               throws RecordingException

Record a port event at the current time.

Throws:

RecordingException

portEvent

public void portEvent(IOPortEvent event,
                      java.util.Date timestamp)
               throws RecordingException

Record a port event at a specific time.

Throws:

RecordingException

refillPortEvent

public void refillPortEvent(IOPortRefillEvent event)
                     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.

Throws:

RecordingException

customProvEvent

public void customProvEvent(ProvenanceEvent event)
                     throws RecordingException

Record a custom provenance event.

Throws:

RecordingException

generateParameters

public RecordingParameters generateParameters(NamedObj no)
                                       throws IllegalActionException,
                                              NameDuplicationException

Add Parameters to ProvenanceListener configuration GUI.

Throws:

IllegalActionException

NameDuplicationException

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute.

Throws:

IllegalActionException

getQueryable

public Queryable getQueryable(boolean allowReconnectWF)
                       throws QueryException,
                              RecordingException

Get a Queryable connected to the Recording output.

Throws:

QueryException - may be thrown if Queryable not implemented for the Recording type.

RecordingException

getContainer

public ProvenanceRecorder getContainer()

Get the container.

setContainer

public void setContainer(ProvenanceRecorder container)

Set the container.

setDebugWriter

public void setDebugWriter(java.io.Writer writer)

Set a Writer for debugging output.

setContainerLSID

public void setContainerLSID(KeplerLSID lsid)

Set the container LSID. This is used when a sub workflow is ran separately at the top level.

setContainerName

public void setContainerName(java.lang.String name)

Set the container name. This is used when a sub workflow is ran separately at the top level.

renamedWorkflow

public void renamedWorkflow(NamedObj namedObj,
                            KeplerLSID oldLSID,
                            KeplerLSID newLSID,
                            java.lang.String oldName,
                            java.lang.String newName)
                     throws RecordingException

A workflow was renamed.

Parameters:

namedObj - the workflow

oldLSID - the previous LSID

newLSID - the new LSID

oldName - the previous name

newName - the new name

Throws:

RecordingException

See Also:

WorkflowRenameListener

tagAdded

public void tagAdded(TagEvent event)
              throws RecordingException

Throws:

RecordingException

tagRemoved

public void tagRemoved(TagEvent event)
                throws RecordingException

Throws:

RecordingException

changeExecutionLSID

public boolean changeExecutionLSID(int execId,
                                   KeplerLSID newExecLSID,
                                   Queryable q)
                            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.

Parameters:

execId -

newExecLSID -

Returns:

Throws:

RecordingException

setStateSerializer

public void setStateSerializer(StateSerializer serializer)

Set the state serializer.

removeStateSerializer

public void removeStateSerializer()

Remove the state serializer.

_debug

protected void _debug(java.lang.String str)

Debugging output.

_debug

protected void _debug(java.lang.Object object)

Debugging output.

_warn

protected void _warn(java.lang.String str)

Warning output.

_error

protected void _error(java.lang.String str)

Error output.

_getExceptionMessage

protected java.lang.String _getExceptionMessage(java.lang.Exception e)

_debugWrite

protected void _debugWrite(java.lang.String str)
                    throws RecordingException

Write to any debug writer.

Throws:

RecordingException

_debugWrite

protected void _debugWrite(java.lang.String str,
                           java.lang.Throwable t)
                    throws RecordingException

Write to any debug writer.

Throws:

RecordingException

_needWorkflowContents

protected void _needWorkflowContents(boolean val)

Set the value for needing workflow contents to be registered.

_updateContainerName

protected void _updateContainerName()

Update the container's name.

_getNameableFullName

protected java.lang.String _getNameableFullName(Nameable nameable)

Get a Nameable's full name including the name of the containing workflow.