public abstract class ALDOperator extends Object implements ALDConfigurationValidator, ALDOperatorExecutionProgressEventListener
The interface consisting of all parameters needs to be define by annotating
the corresponding fields (i.e. member variables) using the Parameter
annotation. The direction of a parameter may be input (IN), output (OUT), or
both input and output (INOUT). A Parameter may be declared to be
supplemental. Supplemental parameters, e.g., control output of debugging
information or return intermediate results. The outputs of the operator are
expected to be independent of the value of these supplemental values which
are not stored in the processing history. A parameter with direction IN or
INOUT which is not supplemental may be declared to be required. For OUT
parameter and supplemental parameters the required field is ignored. If a
parameter of an operator is expected to be documented in the data flow of the
processing history, it may be of any Java class where the instances are by
references. This excludes only primitive data types, interned strings, and
cached numerical objects. If the parameter is not be part of the data flow
all classes are acceptable.
Parameter may be added or removed.
Values of parameters and inputs have to be set prior to invoking the operator
via runOp()
and the resulting outputs may be retrieved from the
operator after return from runOp()
.
A default constructor without arguments has to be implemented for all
features of code generation and generic execution to be available. For
generic execution the operator has to be annotated with
ALDAOperator
with
allowGenericExecution
set to true.
The method operate()
implements the processing of this operator
and has to be overridden when implementing non-abstract operators. All
information passed into and back from the operator are passed via the member
variables of the operator which are properly annotated. This method should by
no means be used to invoke processing of the operator directly, rather
runOp()
is to be used.
The method runOp()
is called by the user of an operator to
invoke processing. runOp()
first checks if all required
parameters and inputs are set to non-null values and subsequently check the
validity of parameters and inputs as defined by the method
validateCustom
which has to be overridden when implementing an
operator.
Refer to the Alida manual for more details and examples.
Modifier and Type | Class and Description |
---|---|
private class |
ALDOperator.DescriptorComparator |
static class |
ALDOperator.HidingMode
Determines the visibility of an operator invocation via
runOp() in
the processing history. |
static class |
ALDOperator.HistoryConstructionMode
Mode of implicit construction of the processing graph.
|
Modifier and Type | Field and Description |
---|---|
protected boolean |
completeDAG
Does this operator prefer a complete DAG or a data dependency DAG.
|
private static ALDOperator.HistoryConstructionMode |
constructionMode
Mode of implicit construction of the processing graph.
|
private boolean |
debug |
(package private) Object |
genuineInstance
Genuine object representing the operation.
|
String |
name
Name of the operator
|
protected EventListenerList |
operatorExecutionEventlistenerList
List of control event listeners attached to this class listening to
ALDOperatorExecutionProgressEvent . |
private ALDOpNode |
opNode
The
opNode of this operator during execution of runOp . |
(package private) static WeakHashMap<Thread,Stack<ALDOpNode>> |
opNodeStackHash
A weak hashmap which contains for each thread a stack of opNodes
reflecting the current state of the method stack.
|
private Hashtable<String,ALDOpParameterDescriptor> |
parameterDescriptorsActive
Hash contains parameter descriptors
for all currently active parameters.
|
private Hashtable<String,ALDOpParameterDescriptor> |
parameterDescriptorsAnnotated
Hash contains parameter descriptors which are annotated.
|
private Hashtable<String,ALDOpParameterDescriptor> |
parameterDescriptorsInactive
Hash contains parameter descriptors which has previous be active but currently inactive, i.e. removed,
for potential later re-use.
|
protected static ALDPortHashAccess |
portHashAccess
Access to the central port hash.
|
protected Boolean |
verbose
Verbose flag to be inherited by all operators.
|
protected ALDVersionProvider |
versionProvider
Instance of a class providing version information.
|
Constructor and Description |
---|
ALDOperator()
This constructor initializes an operator.
|
Modifier and Type | Method and Description |
---|---|
void |
addOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
Adds a listener to this reporter.
|
protected void |
addParameter(ALDOpParameterDescriptor descr)
Add a parameter with the given descriptor to the operator.
|
protected void |
addParameter(String name)
Add a parameter with the given
name to the operator. |
protected void |
addParameterUnconditioned(ALDOpParameterDescriptor descr)
Add a parameter descriptor to the operator without checks or updating of
parameter hashes besides active parameters.
|
(package private) boolean |
allowedClassForIO(Class<?> currentClass)
Is this class allowed as Input and/or Output?
|
protected boolean |
fieldContained(String key)
Does any hash table contain the key, i.e. this field?
|
private Method |
findCallbackMethod(Class<?> c,
String callback)
Find callback method of parameter in class or any of its super classes.
|
private Stack<ALDOpNode> |
findCurrentThreadsOpNodeStack()
Find the opNode stack for the current thread.
|
protected void |
fireOperatorExecutionProgressEvent(ALDOperatorExecutionProgressEvent ev)
Sends an event of changed execution progress to all registered listeners.
|
static ALDPortHashAccess |
getALDPortHashAccessKey()
Get a reference to the port hash access object.
|
static int |
getConstructionMode()
Return the current mode of implicit construction
constructionMode . |
String |
getDocumentation()
Full description of the operator, e.g., to be shown as documentation in GUI.
|
ALDOperator.HidingMode |
getHidingMode()
Return the
hidingMode of this operator during execution
via runOp . |
protected Collection<String> |
getInactiveParameterNames()
Get the names of all parameters
|
Collection<String> |
getInInoutNames()
Get the names of in or inout parameters.
|
Collection<String> |
getInInoutNames(Boolean useRequired)
Get the names of in or inout parameters.
|
Collection<String> |
getInNames(Boolean useRequired)
Get the names of in parameters.
|
Collection<String> |
getInOutNames(Boolean useRequired)
Get the names of inout parameters.
|
List<String> |
getMissingRequiredInputs()
Deprecated.
|
String |
getName()
Get the name of this operator
|
int |
getNumParameters()
Get the number of parameters
|
Collection<String> |
getOutInoutNames()
Get the names of out or inout parameters
|
Collection<String> |
getOutNames()
Get the names of out parameters
|
Object |
getParameter(String name)
Get the value of a parameter specified by name.
|
ALDOpParameterDescriptor |
getParameterDescriptor(String name)
Get the parameter descriptor for given name.
|
protected ALDOpParameterDescriptor |
getParameterDescriptorUnconditioned(String name)
Get the parameter descriptor for given name.
|
Collection<String> |
getParameterNames()
Get the names of all parameters
|
protected Object |
getParameterUnconditioned(String name)
Get the value of a parameter specified by name.
|
Collection<String> |
getSupplementalNames()
Get the names of supplemental parameters
|
Boolean |
getVerbose()
Return the verbose state of this opertor.
|
String |
getVersion()
Get the version of this operator
|
void |
handleOperatorExecutionProgressEvent(ALDOperatorExecutionProgressEvent event)
Method which is called on event occurence.
|
boolean |
hasInOutParameters()
Return true it this operator has at least one INOUT parameter
|
boolean |
hasParameter(String name)
Returns true if the operator has a currently active parameter of the given
name ,
otherwise false. |
private boolean |
includeInHistory(ALDOperator.HidingMode hidingMode,
ALDOperator.HidingMode parentHidingMode)
Is this invocation to be included into the history?
|
boolean |
isAnnotatedParameter(String name)
Returns true if the operator has an annotated parameter
name
irrespective whether this parameter is currently active or not |
boolean |
isConfigured()
Returns true if the object is properly configured.
|
protected abstract void |
operate()
This method does the actual work and needs to be implemented by every
subclass.
|
void |
print()
Print some information of the current state this operator to System.out.
|
void |
print(PrintStream outfile)
Print some information the current state of this operator to
outfile . |
protected void |
print(PrintStream outfile,
boolean printValue)
Print information of the interface and values of this operator to
outfile . |
void |
printInterface()
Print information of the interface of this operator to System.out.
|
void |
printInterface(PrintStream outfile)
Print information of the interface of this operator to
outfile . |
static void |
readHistory(Object obj,
String filename)
Reads and set the history graph of the given object from file.
|
protected Object |
readResolve()
Init function for deserialized objects.
|
void |
reinitializeParameterDescriptors()
Deprecated.
|
void |
removeOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
Removes a listener from this reporter.
|
protected void |
removeParameter(String name)
Remove the descriptor associated with
name . |
void |
runOp()
A legal method to invoke the operator and handles everything necessary to
protocol the processing history.
|
void |
runOp(ALDOperator.HidingMode hidingMode)
A legal method to invoke the operator and handles everything necessary to
protocol the processing history.
|
void |
runOp(boolean hidden)
A legal method to invoke the operator and handles everything necessary to
protocol the processing history.
|
static ALDOperator.HistoryConstructionMode |
setConstructionMode() |
static void |
setConstructionMode(ALDOperator.HistoryConstructionMode constructionMode) |
static void |
setConstructionMode(int cMode)
Set the mode of implicit construction of the processing graph.
|
void |
setHidingMode(ALDOperator.HidingMode hidingMode)
Set the hiding mode of this operator during execution via
runOp . |
protected void |
setName(String name)
Set the name of this operator
|
void |
setParameter(String name,
Object value)
Set the value of a parameter specified by name.
|
protected void |
setParameterUnconditioned(String name,
Object value)
Set the value of a parameter specified by name.
|
void |
setVerbose(Boolean verbose)
Set the verbose state of this opertor.
|
private Collection<ALDOpParameterDescriptor> |
sortedDescriptors(Collection<String> parameterNames)
Return a collection of descriptors for the given parameter named
which is sorted according to DataIoOrder.
|
String |
toStringVerbose()
Returns a string containing printable information about this operator including parameters.
|
List<String> |
unconfiguredItems()
Returns all required IN an INOUT parameters which have a null value
|
void |
validate()
Validates the parameters and inputs of this operator.
|
void |
validateCustom()
Operator specific validation of parameters and inputs.
|
void |
validateGeneric()
Generic validation of the in and inout parameters of this operator.
|
static void |
writeHistory(Object obj,
String filename)
Write the processing history if any to a graphml file.
|
static void |
writeHistory(Object obj,
String filename,
ALDProcessingDAG.HistoryType historyType)
Write the processing history if any to a graphml file.
|
static void |
writeHistory(Object obj,
String filename,
ALDProcessingDAG.HistoryType historyType,
boolean ignoreHiding)
Write the processing history if any to a graphml file.
|
public String name
Object genuineInstance
private ALDOpNode opNode
opNode
of this operator during execution of runOp
.@Parameter(label="Verbose", supplemental=true, direction=IN, description="Verbose flag", mode=ADVANCED) protected Boolean verbose
protected boolean completeDAG
protected static ALDPortHashAccess portHashAccess
static WeakHashMap<Thread,Stack<ALDOpNode>> opNodeStackHash
runOp()
is called, an opNode is created which is associated
with this call. It is pushed onto the stack and popped at the end of
runOp()
. As the first element a opNode for the dummy
operator ALDToplevelOperator is created which represents outer or top
most level of operator calls.private Hashtable<String,ALDOpParameterDescriptor> parameterDescriptorsActive
private Hashtable<String,ALDOpParameterDescriptor> parameterDescriptorsInactive
private Hashtable<String,ALDOpParameterDescriptor> parameterDescriptorsAnnotated
protected ALDVersionProvider versionProvider
private boolean debug
protected transient volatile EventListenerList operatorExecutionEventlistenerList
ALDOperatorExecutionProgressEvent
.private static ALDOperator.HistoryConstructionMode constructionMode
public ALDOperator() throws ALDOperatorException
ALDOperatorException
public static void setConstructionMode(ALDOperator.HistoryConstructionMode constructionMode)
constructionMode
- the constructionMode to setpublic static ALDOperator.HistoryConstructionMode setConstructionMode()
constructionMode
- the constructionMode to setpublic static int getConstructionMode()
constructionMode
.ALDOperatorException
public static void setConstructionMode(int cMode)
cMode
- the constructionMode to setprotected abstract void operate() throws ALDOperatorException, ALDProcessingDAGException
public final String getName()
protected void setName(String name)
public String getDocumentation()
public ALDOperator.HidingMode getHidingMode()
hidingMode
of this operator during execution
via runOp
.public void setHidingMode(ALDOperator.HidingMode hidingMode)
runOp
.
NOTE: A subsequent call of runOp
will reset the hdingMode
according to the argments of this method call.
hidingMode
- public final String getVersion()
public static ALDPortHashAccess getALDPortHashAccessKey()
protected void addParameter(ALDOpParameterDescriptor descr) throws ALDOperatorException
descr
- ALDOperatorException
- of type INVALID_PARAMETERNAME
if parameter already
visible or is inactive but exists as an annotated parameterprotected void addParameter(String name) throws ALDOperatorException
name
to the operator.
A parameter with this name needs to have been active previously and
the descriptor of the last instance of a parameter with this name is (re)used.descr
- ALDOperatorException
- of type INVALID_PARAMETERNAME
if parameter already exists
or was not known/active previously.protected void addParameterUnconditioned(ALDOpParameterDescriptor descr)
descr
- protected void removeParameter(String name) throws ALDOperatorException
name
.name
- ALDOperatorException
public final int getNumParameters()
public final Collection<String> getInInoutNames()
public final Collection<String> getInInoutNames(Boolean useRequired)
useRequired
- If true return only required in or inout parameters, if false
return only not required in or inout parameters. If
null
then return all in or inout parameters.public final Collection<String> getOutInoutNames()
public final Collection<String> getInNames(Boolean useRequired)
useRequired
- If true return only required in parameters, if false return
only not required in parameters. If null
then
return all in parameters.public final Collection<String> getOutNames()
public final Collection<String> getInOutNames(Boolean useRequired)
useRequired
- If true return only required inout parameters, if false return
only not required inout parameters. If null
then
return all inout parameters.public boolean hasInOutParameters()
public final Collection<String> getSupplementalNames()
public final Collection<String> getParameterNames()
protected final Collection<String> getInactiveParameterNames()
public boolean hasParameter(String name)
name
,
otherwise false.name
- name
existspublic boolean isAnnotatedParameter(String name)
name
irrespective whether this parameter is currently active or notname
- public final ALDOpParameterDescriptor getParameterDescriptor(String name) throws ALDOperatorException
name
- Name of the parameter to get the new value forALDOperatorException
- of type INVALID_PARAMETERNAME
if the parameter is not active (or does not exists)protected final ALDOpParameterDescriptor getParameterDescriptorUnconditioned(String name) throws ALDOperatorException
name
- Name of the parameter to get the new value forALDOperatorException
- of type INVALID_PARAMETERNAME
if the parameter does not existpublic Object getParameter(String name) throws ALDOperatorException
name
- Name of the parameter to get the new value forALDOperatorException
- of type INVALID_PARAMETERNAME
if the parameter is not active or does not existprotected Object getParameterUnconditioned(String name) throws ALDOperatorException
name
- Name of the parameter to get the new value forALDOperatorException
- of type INVALID_PARAMETERNAME
if the parameter is not active or does not existpublic void setParameter(String name, Object value) throws ALDOperatorException
name
- Name of the parameter to set a new value forvalue
- new valueALDOperatorException
- of type if the
parameter does not exist and of type CALLBACK_ERROR
if the callback function may not be invoked or its invocations
results in an exception
protected void setParameterUnconditioned(String name, Object value) throws ALDOperatorException
name
- Name of the parameter to set a new value forvalue
- new valueALDOperatorException
- of type if the
parameter does not exist and of type CALLBACK_ERROR
if the callback function may not be invoked or its invocations
results in an exception
private Method findCallbackMethod(Class<?> c, String callback)
c
- Class of parameter object in question.callback
- Callback function to be searched for.protected Object readResolve()
This function is called on an instance of this class being deserialized from file, prior to handing the instance over to the user. It takes care of a proper initialization of transient member variables as they are not initialized to the default values during deserialization.
@Deprecated public void reinitializeParameterDescriptors()
public final void runOp() throws ALDOperatorException, ALDProcessingDAGException
runOp( HidingMode.VISIBLE)
, i.e. runs the operator as visible in the history.ALDOperatorException
ALDProcessingDAGException
runOp(boolean)
public final void runOp(boolean hidden) throws ALDOperatorException, ALDProcessingDAGException
hidden
is true this call has the same effect as
runOp( HidingMode.HIDDEN)
, i.e. runs the operator as hidden.
If hidden
is false this call has the same effect as
runOp( HidingMode.VISIBLE)
, i.e. runs the operator as visible.ALDOperatorException
ALDProcessingDAGException
runOp(boolean)
public final void runOp(ALDOperator.HidingMode hidingMode) throws ALDOperatorException, ALDProcessingDAGException
runOp
, all
IN and INOUT parameters have to be set. When called runOp
first validates the parameters. Validity requires for all operators, that
all required IN and INOUT parameters to have non null values. In addition
the implementation of an operator may impose further constrains defined
by the method validateCustom
which e.g. may restrict the
interval of numerical parameters.
After successful validation the operate
method is called to
do the actuall processing of this operator. Upon return from
runOp
, resulting output data may be retrieved from the
operator object.
hidingMode
determines the visibility of this invocation in the processing history.
If hidingMode
equals null
this is equivalent to
hidingMode
equal VISIBLE
(for backward compatibility).
hidingMode
- Determines the visibility of this invocation in the processing historyALDOperatorException
ALDProcessingDAGException
private boolean includeInHistory(ALDOperator.HidingMode hidingMode, ALDOperator.HidingMode parentHidingMode)
private Stack<ALDOpNode> findCurrentThreadsOpNodeStack()
public final void validate() throws ALDOperatorException
validateCustom
. An
ALDOperatorException is thrown if either validation fails.ALDOperatorException
public final void validateGeneric() throws ALDOperatorException
ALDOperatorException
@Deprecated public List<String> getMissingRequiredInputs()
public List<String> unconfiguredItems()
unconfiguredItems
in interface ALDConfigurationValidator
public void validateCustom() throws ALDOperatorException
ALDOperatorException
public boolean isConfigured()
ALDConfigurationValidator
isConfigured
in interface ALDConfigurationValidator
public void setVerbose(Boolean verbose) throws ALDOperatorException
verbose
- New verbose stateALDOperatorException
public Boolean getVerbose() throws ALDOperatorException
ALDOperatorException
public static void readHistory(Object obj, String filename)
obj
- Object for which the history is to be read.filename
- File from where the history is to be read.ALDPortHashAccess.readHistory(Object,String)
public static void writeHistory(Object obj, String filename) throws ALDProcessingDAGException, ALDOperatorException
writeHistory(obj, filename, ALDProcessingDAG.HistoryType.OPNODETYPE, false)
obj
- Object for which the history to write for.filename
- Filename to write the processing history into.
For handling of extensions see
ALDPortHashAccess.writeHistory(Object, String, de.unihalle.informatik.Alida.operator.ALDProcessingDAG.HistoryType, boolean)
ALDProcessingDAGException
ALDOperatorException
public static void writeHistory(Object obj, String filename, ALDProcessingDAG.HistoryType historyType) throws ALDProcessingDAGException, ALDOperatorException
writeHistory(obj, filename, historyType, false)
obj
- Object for which the history to write for.filename
- Filename to write the processing history into.
For handling of extensions see
ALDPortHashAccess.writeHistory(Object, String, de.unihalle.informatik.Alida.operator.ALDProcessingDAG.HistoryType, boolean)
historyType
- Type/mode of the history.ALDProcessingDAGException
ALDOperatorException
public static void writeHistory(Object obj, String filename, ALDProcessingDAG.HistoryType historyType, boolean ignoreHiding) throws ALDProcessingDAGException, ALDOperatorException
obj
- Object for which the history to write for.filename
- Filename to write the processing history into ingraphml/XML
format.
For handling of extensions see
ALDPortHashAccess.writeHistory(Object, String, de.unihalle.informatik.Alida.operator.ALDProcessingDAG.HistoryType, boolean)
historyType
- Type/mode of the history.ignoreHiding
- If true, hiding of opNodes is ignored.ALDProcessingDAGException
ALDOperatorException
ALDPortHashAccess.writeHistory(Object,String,ALDProcessingDAG.HistoryType,boolean)
public void addOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
listener
- Listener to be added.public void removeOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
listener
- Listener to be removed.protected void fireOperatorExecutionProgressEvent(ALDOperatorExecutionProgressEvent ev)
ev
- Event to be send to all listeners.public void print()
public void print(PrintStream outfile)
outfile
.outfile
- Stream to print onpublic void printInterface()
public void printInterface(PrintStream outfile)
outfile
.outfile
- Stream to print onprotected void print(PrintStream outfile, boolean printValue)
outfile
. If printValue is true, additional the current value
is printed. This method note intended for public use.outfile
- Stream to print onprintValue
- public String toStringVerbose()
boolean allowedClassForIO(Class<?> currentClass)
protected boolean fieldContained(String key)
private Collection<ALDOpParameterDescriptor> sortedDescriptors(Collection<String> parameterNames)
parameterNames
- public void handleOperatorExecutionProgressEvent(ALDOperatorExecutionProgressEvent event) throws ALDWorkflowException
ALDOperatorExecutionProgressEventListener
handleOperatorExecutionProgressEvent
in interface ALDOperatorExecutionProgressEventListener
event
- Event to be handled.ALDWorkflowException
Copyright © 2010–2021 Martin Luther University Halle-Wittenberg, Institute of Computer Science, Pattern Recognition and Bioinformatics. All rights reserved.