org.kepler.provenance

Class ProvenanceRecorder

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

org.kepler.provenance.ProvenanceRecorder

All Implemented Interfaces:

java.lang.Cloneable, SshEventListener, TagEventListener, WorkflowRenameListener, ActorFiringListener, ExecutionListener, Initializable, IOPortEventListener, Changeable, ChangeListener, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, ValueListener

public class ProvenanceRecorder
extends Attribute
implements ExecutionListener, ChangeListener, IOPortEventListener, ActorFiringListener, DebugListener, ValueListener, SshEventListener, Initializable, WorkflowRenameListener, TagEventListener

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 Recording implementation.

Author:

Daniel Crawl

See Also:

Recording

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
StringParameter	containerWorkflowLSID The LSID of the containing workflow.
StringParameter	containerWorkflowName The name of the containing workflow.
static java.lang.String	DEFAULT_REC_TYPE_IGNORE String used when disabling provenance recording
Parameter	delayRecordingSpecification If true, delay recording specification as long as possible.
StringParameter	hostname Local hostname.
StringParameter	recordingType Which Recording to use.
Parameter	recordTokens Record token values.
StringParameter	username Username.

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Constructors

Constructor and Description
ProvenanceRecorder() Construct a provenance recorder in the default workspace using the TOP Recorder Name specified in the configuration file.
ProvenanceRecorder(CompositeEntity container) Construct a provenance recorder using the specified container.
ProvenanceRecorder(CompositeEntity container, java.lang.String name) Construct a provenance recorder in the given container with the given name.
ProvenanceRecorder(ConfigurationProperty configProperty) Construct a provenance recorder in the default workspace using non-default ConfigurationProperty.
ProvenanceRecorder(Workspace workspace) Construct a provenance recorder in the workspace with an empty name.

Method Summary

Modifier and Type	Method and Description
void	addEnabledListener(ProvenanceEnabledListener listener) Add a ProvenanceEnabledListener to be notified when provenance is enabled/disabled.
void	addInitializable(Initializable initializable) 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.
void	addPiggyback(Recording recording) Add the specified recording to the list of recordings notified for each provenance event.
static void	addPiggybackForFuture(Recording recording) Add the specified recording to the list of recordings that receive provenance events from all ProvenanceRecorders created in the future.
static boolean	addProvenanceRecorder(CompositeActor container, ProvenanceEnabledListener listener, Effigy effigy) Add the default provenance recorder to a container if it does not already contain a provenance recorder.
void	addRecordingType(java.lang.String typeName, java.lang.String typeImpl) Add a recording type.
void	attributeChanged(Attribute attribute) React to attribute change (of ProvenanceRecorder only).
void	changeExecuted(ChangeRequest change) React to a change request has been successfully executed.
void	changeFailed(ChangeRequest change, java.lang.Exception exception) React to a change request has resulted in an exception.
boolean	checkForSupportedDirector() Check if the director is supported.
java.lang.Object	clone(Workspace workspace) Clone the ProvenanceRecorder into a specified workspace.
static boolean	containsSupportedDirector(CompositeActor composite) Returns true if the composite actor contains a director supported by the provenance recorder or no director.
void	disconnect() Perform cleanup.
static void	disconnectAll() Perform cleanup for all ProvenanceRecorder instances.
void	event(DebugEvent event) React to a generic debug event.
void	executionError(Manager manager, java.lang.Throwable throwable) Report an execution failure.
void	executionFinished(Manager manager) Report that the current execution has finished and the wrapup sequence has completed normally.
void	executionImported(KeplerLSID execLSID) Report that an execution has been imported
void	firingEvent(FiringEvent event) React to an actor firing.
static ProvenanceRecorder	getDefaultProvenanceRecorder(NamedObj namedObj) Get the provenance recorder with for a NamedObj.
static Queryable	getDefaultQueryable(NamedObj namedObj) Get a queryable from the default provenance recorder for a NamedObj.
static java.util.Map<java.lang.String,java.lang.String>	getDefaultsMap() Return a Map of the default settings.
KeplerLSID	getExecutionLSID() Get the execution LSID.
static java.util.List<Recording>	getFuturisticPiggybacks(Recording recording) Return list of recordings that receive provenance events from all ProvenanceRecorders created in the future.
Recording	getRecording() Get the current recording.
RecordingParameters	getRecordingParameters() Get current RecordingParameters.
java.util.Map<java.lang.String,java.lang.String>	getSettingsMap() Return a Map of the settings, returns default settings if necessary
void	initialize() Invoke the initialize methods and check for additional MultiInstanceComposite actors created after preinitialize().
boolean	isEnabled() Return true if provenance output is turned on.
void	loadRecordingTypes() Load the default recording types.
void	loadRecordingTypes(java.io.File file) Load the recording types from a specific file.
void	managerStateChanged(Manager manager) Report that the manager has changed state.
void	portEvent(IOPortEvent event) React to a port read or write.
void	preinitialize() 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.
void	removeEnabledListener(ProvenanceEnabledListener listener) Remove a ProvenanceEnabledListener from the set of listeners.
void	removeInitializable(Initializable 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.
void	removePiggyback(Recording recording) Remove the specified recording from the list of recordings notified for each provenance event.
static void	removePiggybackForFuture(Recording recording) Remove the specified recording from the list of recordings that receive provenance events from all ProvenanceRecorders created in the future.
void	removeRecordingType(java.lang.String typeName) Remove a recording type.
void	removeStateSerializer() Remove the state serializer.
void	renamedWorkflow(NamedObj namedObj, KeplerLSID oldLSID, KeplerLSID newLSID, java.lang.String oldName, java.lang.String newName) A workflow was renamed.
void	saveRecordingTypes(java.lang.String file, java.lang.String header) Save the recording types to a specific properties file.
void	setContainer(NamedObj container) Change the container.
void	setDebugWriter(java.io.Writer writer) Set a writer for debugging output.
void	setPersistentParameters(boolean persistent) Set the persistence of parameters.
void	setStateSerializer(StateSerializer serializer) Set the state serializer for recordings.
void	sshEvent(SshEvent event) React to an ssh event.
void	tagAdded(TagEvent event)
void	tagRemoved(TagEvent event)
void	valueChanged(Settable settable) React to a change in parameter value.
void	wrapup() Perform clean up.

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _description, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.kernel.util.DebugListener

message

Field Detail

delayRecordingSpecification

public Parameter delayRecordingSpecification

If true, delay recording specification as long as possible.

recordingType

public StringParameter recordingType

Which Recording to use.

recordTokens

public Parameter recordTokens

Record token values.

hostname

public StringParameter hostname

Local hostname.

username

public StringParameter username

Username.

DEFAULT_REC_TYPE_IGNORE

public static final java.lang.String DEFAULT_REC_TYPE_IGNORE

String used when disabling provenance recording

See Also:

Constant Field Values

containerWorkflowLSID

public StringParameter containerWorkflowLSID

The LSID of the containing workflow.

containerWorkflowName

public StringParameter containerWorkflowName

The name of the containing workflow.

Constructor Detail

ProvenanceRecorder

public ProvenanceRecorder()
                   throws IllegalActionException,
                          NameDuplicationException

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.

Throws:

IllegalActionException

NameDuplicationException

ProvenanceRecorder

public ProvenanceRecorder(ConfigurationProperty configProperty)
                   throws IllegalActionException,
                          NameDuplicationException

Construct a provenance recorder in the default workspace using non-default ConfigurationProperty.

Parameters:

configProperty -

Throws:

IllegalActionException

NameDuplicationException

ProvenanceRecorder

public ProvenanceRecorder(CompositeEntity container)
                   throws IllegalActionException,
                          NameDuplicationException

Construct a provenance recorder using the specified container. The name is set from the TOP Recorder Name specified in the configuration file.

Parameters:

container - the container of the provenance recorder.

Throws:

IllegalActionException

NameDuplicationException

ProvenanceRecorder

public ProvenanceRecorder(Workspace workspace)
                   throws IllegalActionException,
                          NameDuplicationException

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.

Parameters:

workspace - The workspace for this object.

Throws:

IllegalActionException

NameDuplicationException

ProvenanceRecorder

public ProvenanceRecorder(CompositeEntity container,
                          java.lang.String name)
                   throws IllegalActionException,
                          NameDuplicationException

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.

Parameters:

container - Container of the director.

name - Name of this listener.

Throws:

IllegalActionException - If the listener is not compatible with the specified container. May be thrown in a derived class.

NameDuplicationException - If the container is not a CompositeActor and the name collides with an entity in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to attribute change (of ProvenanceRecorder only).

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the function is not recognized.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the ProvenanceRecorder into a specified workspace.

Overrides:

clone in class Attribute

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Change the container. If previously in a container, stop listening. If put into a new container, start listening to that container.

Overrides:

setContainer in class Attribute

Parameters:

container - The container to attach this attribute to..

Throws:

IllegalActionException - If this attribute is not of the expected class for the container, or it has no name, or the attribute and container are not in the same workspace, or the proposed container would result in recursive containment.

NameDuplicationException - If the container already has an attribute with the name of this attribute.

See Also:

Attribute.getContainer()

disconnect

public void disconnect()
                throws IllegalActionException

Perform cleanup.

Throws:

IllegalActionException

disconnectAll

public static void disconnectAll()
                          throws IllegalActionException

Perform cleanup for all ProvenanceRecorder instances.

Throws:

IllegalActionException

isEnabled

public boolean isEnabled()
                  throws IllegalActionException

Return true if provenance output is turned on.

Throws:

IllegalActionException

addEnabledListener

public void addEnabledListener(ProvenanceEnabledListener listener)

Add a ProvenanceEnabledListener to be notified when provenance is enabled/disabled.

removeEnabledListener

public void removeEnabledListener(ProvenanceEnabledListener listener)

Remove a ProvenanceEnabledListener from the set of listeners.

preinitialize

public void preinitialize()
                   throws IllegalActionException

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.

Specified by:

preinitialize in interface Initializable

Throws:

IllegalActionException - If initializing is not permitted.

initialize

public void initialize()
                throws IllegalActionException

Invoke the initialize methods and check for additional MultiInstanceComposite actors created after preinitialize(). of objects that have been added using addInitializable().

Specified by:

initialize in interface Initializable

Throws:

IllegalActionException - If one of the added objects throws it.

wrapup

public void wrapup()
            throws IllegalActionException

Perform clean up. This method is executed when the manager is finishing model execution.

Specified by:

wrapup in interface Initializable

Throws:

IllegalActionException - If wrapup is not permitted.

addInitializable

public void addInitializable(Initializable initializable)

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.

Specified by:

addInitializable in interface Initializable

Parameters:

initializable - The object whose methods should be invoked.

See Also:

removeInitializable(Initializable), CompositeActor.addPiggyback(Executable)

removeInitializable

public void removeInitializable(Initializable 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.

Specified by:

removeInitializable in interface Initializable

Parameters:

initializable - The object whose methods should no longer be invoked.

See Also:

addInitializable(Initializable), CompositeActor.removePiggyback(Executable)

changeExecuted

public void changeExecuted(ChangeRequest change)

React to a change request has been successfully executed.

Specified by:

changeExecuted in interface ChangeListener

Parameters:

change - The change that has been executed, or null if the change was not done via a ChangeRequest.

changeFailed

public void changeFailed(ChangeRequest change,
                         java.lang.Exception exception)

React to a change request has resulted in an exception.

Specified by:

changeFailed in interface ChangeListener

Parameters:

change - The change that was attempted or null if the change was not done via a ChangeRequest.

exception - The exception that resulted.

executionError

public void executionError(Manager manager,
                           java.lang.Throwable throwable)

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).

Specified by:

executionError in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

throwable - The throwable to report.

executionFinished

public void executionFinished(Manager manager)

Report that the current execution has finished and the wrapup sequence has completed normally.

Specified by:

executionFinished in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

executionImported

public void executionImported(KeplerLSID execLSID)

Report that an execution has been imported

managerStateChanged

public void managerStateChanged(Manager manager)

Report that the manager has changed state.

Specified by:

managerStateChanged in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

See Also:

Manager.getState()

portEvent

public void portEvent(IOPortEvent event)
               throws IllegalActionException

React to a port read or write.

Specified by:

portEvent in interface IOPortEventListener

Parameters:

event - The event representing the token(s).

Throws:

IllegalActionException - If thrown by the implementation.

firingEvent

public void firingEvent(FiringEvent event)

React to an actor firing.

Specified by:

firingEvent in interface ActorFiringListener

Parameters:

event - The event representing the token(s) sent.

event

public void event(DebugEvent event)

React to a generic debug event. Actors and directors may use this interface to inform listeners of firing events.

Specified by:

event in interface DebugListener

Overrides:

event in class NamedObj

Parameters:

event - The event.

addRecordingType

public void addRecordingType(java.lang.String typeName,
                             java.lang.String typeImpl)
                      throws IllegalActionException

Add a recording type.

Throws:

IllegalActionException

removeRecordingType

public void removeRecordingType(java.lang.String typeName)
                         throws IllegalActionException

Remove a recording type.

Throws:

IllegalActionException

loadRecordingTypes

public void loadRecordingTypes()
                        throws IllegalActionException

Load the default recording types.

Throws:

IllegalActionException

loadRecordingTypes

public void loadRecordingTypes(java.io.File file)
                        throws IllegalActionException

Load the recording types from a specific file.

Throws:

IllegalActionException

saveRecordingTypes

public void saveRecordingTypes(java.lang.String file,
                               java.lang.String header)
                        throws IllegalActionException

Save the recording types to a specific properties file.

Parameters:

file - the properties file path.

header - optional header for properties file.

Throws:

IllegalActionException

valueChanged

public void valueChanged(Settable settable)

React to a change in parameter value.

Specified by:

valueChanged in interface ValueListener

Parameters:

settable - The object that has changed value.

sshEvent

public void sshEvent(SshEvent event)

React to an ssh event.

Specified by:

sshEvent in interface SshEventListener

Parameters:

event - The event to report.

renamedWorkflow

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

A workflow was renamed.

Specified by:

renamedWorkflow in interface WorkflowRenameListener

Parameters:

namedObj - the workflow

oldLSID - the previous LSID

newLSID - the new LSID

oldName - the previous name

newName - the new name

See Also:

WorkflowRenameListener

tagAdded

public void tagAdded(TagEvent event)

Specified by:

tagAdded in interface TagEventListener

tagRemoved

public void tagRemoved(TagEvent event)

Specified by:

tagRemoved in interface TagEventListener

setDebugWriter

public void setDebugWriter(java.io.Writer writer)

Set a writer for debugging output.

getDefaultProvenanceRecorder

public static ProvenanceRecorder getDefaultProvenanceRecorder(NamedObj namedObj)

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.

getDefaultQueryable

public static Queryable getDefaultQueryable(NamedObj namedObj)
                                     throws QueryException,
                                            RecordingException

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.

Throws:

QueryException

RecordingException

getRecordingParameters

public RecordingParameters getRecordingParameters()

Get current RecordingParameters. XXX how does this differ from attributeList()?

getRecording

public Recording getRecording()

Get the current recording.

setPersistentParameters

public void setPersistentParameters(boolean persistent)

Set the persistence of parameters.

addPiggyback

public void addPiggyback(Recording recording)

Add the specified recording to the list of recordings notified for each provenance event. NOTE: the recordings are notified after the internal Recording.

Parameters:

recording - the Recording to be notified

removePiggyback

public void removePiggyback(Recording recording)

Remove the specified recording from the list of recordings notified for each provenance event.

Parameters:

recording - the Recording to remove

See Also:

addPiggyback(org.kepler.provenance.Recording)

addPiggybackForFuture

public static void addPiggybackForFuture(Recording recording)

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.

Parameters:

recording - the Recording to be notified

removePiggybackForFuture

public static void removePiggybackForFuture(Recording recording)

Remove the specified recording from the list of recordings that receive provenance events from all ProvenanceRecorders created in the future.

Parameters:

recording - the Recording to remove

See Also:

addPiggybackForFuture(org.kepler.provenance.Recording)

getFuturisticPiggybacks

public static java.util.List<Recording> getFuturisticPiggybacks(Recording recording)

Return list of recordings that receive provenance events from all ProvenanceRecorders created in the future.

Parameters:

recording -

Returns:

_futurePiggybacks

containsSupportedDirector

public static boolean containsSupportedDirector(CompositeActor composite)

Returns true if the composite actor contains a director supported by the provenance recorder or no director.

checkForSupportedDirector

public boolean checkForSupportedDirector()
                                  throws IllegalActionException

Check if the director is supported. If it is not, then provenance recording is turned off.

Throws:

IllegalActionException

getExecutionLSID

public KeplerLSID getExecutionLSID()

Get the execution LSID. If the model is not running, returns null.

addProvenanceRecorder

public static boolean addProvenanceRecorder(CompositeActor container,
                                            ProvenanceEnabledListener listener,
                                            Effigy effigy)
                                     throws IllegalActionException,
                                            NameDuplicationException

Add the default provenance recorder to a container if it does not already contain a provenance recorder.

Parameters:

container - The container in which to add the default provenance recorder.

listener - Register this object to listen for provenance enabled events. This parameter can be null.

effigy - The effigy displaying the container. This parameter can be null.

Returns:

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.

Throws:

IllegalActionException

NameDuplicationException

setStateSerializer

public void setStateSerializer(StateSerializer serializer)

Set the state serializer for recordings.

removeStateSerializer

public void removeStateSerializer()

Remove the state serializer.

getSettingsMap

public java.util.Map<java.lang.String,java.lang.String> getSettingsMap()

Return a Map of the settings, returns default settings if necessary

getDefaultsMap

public static java.util.Map<java.lang.String,java.lang.String> getDefaultsMap()

Return a Map of the default settings.