de.unihalle.informatik.Alida.operator
Class ALDOperator

java.lang.Object
  extended by de.unihalle.informatik.Alida.operator.ALDOperator
Direct Known Subclasses:
ALDOperatorControllable, ALDSummarizeArrayOp, ALDToplevelOperator, ApplyToMatrix, MatrixSum, NormalizeExperimentalDataOp

public abstract class ALDOperator
extends java.lang.Object

This is the abstract super class for all Alida operators. Alida opertators facilitate automatic logging of the processing historys and automatic generation of user interfaces.

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 parapeters, 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.

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.

Author:
posch

Field Summary
protected  boolean completeDAG
          Does this operator prefer a complete DAG or a data dependency DAG.
private  int constructionMode
          Mode of implicit construction of the processing graph.
private  boolean debug
           
 java.lang.String name
          Name of the operator
(package private) static java.util.WeakHashMap<java.lang.Thread,java.util.Stack<ALDOpNode>> opNodeStackHash
          A weak hashmap which contains for each thread a stack of opNodes reflecting the current state of the method stack.
private  java.util.Hashtable<java.lang.String,ALDOpParameterDescriptor> parameterDescriptorsAll
          Hash representing the interface of this operator.
protected static ALDPortHashAccess portHashAccess
          Access to the central port hash.
protected  java.lang.Boolean verbose
          Verbose flag to be inherited by all operators.
protected  ALDVersionProvider versionProvider
          Instance of a class providing version information.
 
Constructor Summary
protected ALDOperator()
          This constructor initializes an operator.
 
Method Summary
(package private)  boolean allowedClassForIO(java.lang.Class currentClass)
          Is this class allowed as Input and/or Output?
 ALDOperator deserializeFromXmlFile(java.lang.String filename)
          Deserializes an operator state from the given file.
private  boolean fieldContained(java.lang.String key)
          Does any hashtable contain the key, i.e. this field?
private  java.util.Stack<ALDOpNode> findCurrentThreadsOpNodeStack()
          Find the opNode stack for the current thread.
static ALDPortHashAccess getALDPortHashAccessKey()
          Get a reference to the port hash access object.
 java.util.Collection<java.lang.String> getInInoutNames()
          Get the names of in or inout parameters.
 java.util.Collection<java.lang.String> getInInoutNames(java.lang.Boolean useRequired)
          Get the names of in or inout parameters.
 java.lang.String getName()
          Get the name of this operator
 int getNumParameters()
          Get the number of parameters
 java.util.Collection<java.lang.String> getOutInoutNames()
          Get the names of out or inout parameters
 java.lang.Object getParameter(java.lang.String name)
          Get the value of a parameter specified by name.
 ALDOpParameterDescriptor getParameterDescriptor(java.lang.String name)
          Get the parameter descriptor for given name.
 java.util.Collection<java.lang.String> getParameterNames()
          Get the names of all parameters
 java.util.Collection<java.lang.String> getSupplementalNames()
          Get the names of supplemental parameters
 java.lang.Boolean getVerbose()
          Return the verbose state of this opertor.
 java.lang.String getVersion()
          Get the version of this operator
protected abstract  void operate()
          This method does the actual work and needs to be implemented by every subclass.
 org.apache.xmlbeans.XmlObject parametersToXmlObject()
          Parse the parameter values to an XmlObject.
 void print()
          Print some information of the current state this operator to System.out.
 void print(java.io.PrintStream outfile)
          Print some information the current state of this operator to outfile.
protected  void print(java.io.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(java.io.PrintStream outfile)
          Print information of the interface of this operator to outfile.
static void readHistory(java.lang.Object obj, java.lang.String filename)
          Reads and set the history graph of the given object from file.
 void runOp()
          A legal method to invoke the operator and handles everything necessary to protocol the processing history.
 void runOp(ALDOperator callingOperator)
          Deprecated. 
 void runOp(boolean hidden)
          A legal method to invoke the operator and handles everything necessary to protocol the processing history.
 void serializeToXmlFile(java.lang.String filename)
          Serializes the operator to an XML file.
 void setParameter(java.lang.String name, java.lang.Object value)
          Set the value of a parameter specified by name.
 java.lang.String setParametersFromXml(java.lang.String filename)
          Set the parameter values as read from an Xml file.
 java.lang.String setParametersFromXml(java.lang.String filename, java.lang.String className, java.lang.String packageName)
          Set the parameter values as read from an Xml file.
 void setVerbose(java.lang.Boolean verbose)
          Set the verbose state of this opertor.
 java.lang.String toString()
          Returns a string containing printale information about this operator.
 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(java.lang.Object obj, java.lang.String filename)
          Write the processing history if any to a graphml file.
static void writeHistory(java.lang.Object obj, java.lang.String filename, ALDProcessingDAG.HistoryType historyType)
          Write the processing history if any to a graphml file.
static void writeHistory(java.lang.Object obj, java.lang.String filename, ALDProcessingDAG.HistoryType historyType, boolean ignoreHiding)
          Write the processing history if any to a graphml file.
 void writeParametersToXml(java.lang.String filename)
          Write the parameter values to an xml file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

completeDAG

protected boolean completeDAG
Does this operator prefer a complete DAG or a data dependency DAG. This field may be changed when implementing an operator.


constructionMode

private int constructionMode
Mode of implicit construction of the processing graph. Still experimental at this point!! 0 = regular construction 1 = do not create opNodes for hidden operator invocations 2 = prevent implicit construction completely


debug

private boolean debug

name

public final java.lang.String name
Name of the operator


opNodeStackHash

static java.util.WeakHashMap<java.lang.Thread,java.util.Stack<ALDOpNode>> opNodeStackHash
A weak hashmap which contains for each thread a stack of opNodes reflecting the current state of the method stack. Whenever 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.


parameterDescriptorsAll

private java.util.Hashtable<java.lang.String,ALDOpParameterDescriptor> parameterDescriptorsAll
Hash representing the interface of this operator. It contains descriptors for all annotated parameters collected from this operator and all its super classes.


portHashAccess

protected static ALDPortHashAccess portHashAccess
Access to the central port hash.


verbose

@Parameter(label="Verbose",
           supplemental=true,
           direction=IN,
           description="Verbose flag")
protected java.lang.Boolean verbose
Verbose flag to be inherited by all operators.


versionProvider

protected ALDVersionProvider versionProvider
Instance of a class providing version information.

Constructor Detail

ALDOperator

protected ALDOperator()
               throws ALDOperatorException
This constructor initializes an operator. The name is retrieved from the classname and the parameter hash is initialized.

Throws:
ALDOperatorException
Method Detail

allowedClassForIO

boolean allowedClassForIO(java.lang.Class currentClass)
Is this class allowed as Input and/or Output?


deserializeFromXmlFile

public ALDOperator deserializeFromXmlFile(java.lang.String filename)
Deserializes an operator state from the given file.

Only transient members are ignored.

Parameters:
filename - File from where to read the data.

fieldContained

private boolean fieldContained(java.lang.String key)
Does any hashtable contain the key, i.e. this field?


findCurrentThreadsOpNodeStack

private java.util.Stack<ALDOpNode> findCurrentThreadsOpNodeStack()
Find the opNode stack for the current thread. Create a new one, if not existing

Returns:
opNode stack for the current thread

getALDPortHashAccessKey

public static ALDPortHashAccess getALDPortHashAccessKey()
Get a reference to the port hash access object.

Returns:
reference to the port hash access object

getInInoutNames

public final java.util.Collection<java.lang.String> getInInoutNames()
Get the names of in or inout parameters.

Returns:
names of in or inout parameters

getInInoutNames

public final java.util.Collection<java.lang.String> getInInoutNames(java.lang.Boolean useRequired)
Get the names of in or inout parameters.

Parameters:
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.
Returns:
names of in or inout parameters

getName

public final java.lang.String getName()
Get the name of this operator

Returns:
name of the operator

getNumParameters

public final int getNumParameters()
Get the number of parameters

Returns:
number of parameters

getOutInoutNames

public final java.util.Collection<java.lang.String> getOutInoutNames()
Get the names of out or inout parameters

Returns:
names of out or inout parameters

getParameter

public final java.lang.Object getParameter(java.lang.String name)
                                    throws ALDOperatorException
Get the value of a parameter specified by name.

Parameters:
name - Name of the parameter to get the new value for
Returns:
value of the parameter
Throws:
ALDOperatorException

getParameterDescriptor

public final ALDOpParameterDescriptor getParameterDescriptor(java.lang.String name)
                                                      throws ALDOperatorException
Get the parameter descriptor for given name.

Parameters:
name - Name of the parameter to get the new value for
Returns:
descriptor value
Throws:
ALDOperatorException

getParameterNames

public final java.util.Collection<java.lang.String> getParameterNames()
Get the names of all parameters

Returns:
collection of all parameter names

getSupplementalNames

public final java.util.Collection<java.lang.String> getSupplementalNames()
Get the names of supplemental parameters

Returns:
names of supplemental parameters

getVerbose

public java.lang.Boolean getVerbose()
                             throws ALDOperatorException
Return the verbose state of this opertor.

Returns:
Current verbose state
Throws:
ALDOperatorException

getVersion

public final java.lang.String getVersion()
Get the version of this operator

Returns:
version of the operator

operate

protected abstract void operate()
                         throws ALDOperatorException,
                                ALDProcessingDAGException
This method does the actual work and needs to be implemented by every subclass.

Throws:
ALDOperatorException
ALDProcessingDAGException

parametersToXmlObject

public org.apache.xmlbeans.XmlObject parametersToXmlObject()
                                                    throws org.apache.xmlbeans.XmlException
Parse the parameter values to an XmlObject. Uses xstream for serialization.

Returns:
serialization of the paraeter of this operator
Throws:
org.apache.xmlbeans.XmlException

print

public void print()
Print some information of the current state this operator to System.out.


print

public void print(java.io.PrintStream outfile)
Print some information the current state of this operator to outfile.

Parameters:
outfile - Stream to print on

print

protected void print(java.io.PrintStream outfile,
                     boolean printValue)
Print information of the interface and values of this operator to outfile. If printValue is true, additional the current value is printed. This method note intended for public use.

Parameters:
outfile - Stream to print on
printValue -

printInterface

public void printInterface()
Print information of the interface of this operator to System.out.


printInterface

public void printInterface(java.io.PrintStream outfile)
Print information of the interface of this operator to outfile.

Parameters:
outfile - Stream to print on

readHistory

public static void readHistory(java.lang.Object obj,
                               java.lang.String filename)
Reads and set the history graph of the given object from file.

Parameters:
obj - Object for which the history is to be read.
filename - File from where the history is to be read.
See Also:
ALDPortHashAccess.readHistory(Object,String)

runOp

public final void runOp()
                 throws ALDOperatorException,
                        ALDProcessingDAGException
A legal method to invoke the operator and handles everything necessary to protocol the processing history. This call has the same effect as runOp( false), i.e. runs the operator as not hidden.

Throws:
ALDOperatorException
ALDProcessingDAGException
See Also:
runOp(boolean)

runOp

@Deprecated
public final void runOp(ALDOperator callingOperator)
                 throws ALDOperatorException,
                        ALDProcessingDAGException
Deprecated. 

A legal method to invoke the operator and handles everything necessary to protocol the processing history. This call has the same effect as runOp( false), i.e. runs the operator as not hidden.

Parameters:
callingOperator - Parent operator which invokes this operator
Throws:
ALDOperatorException
ALDProcessingDAGException
See Also:
runOp(boolean)

runOp

public final void runOp(boolean hidden)
                 throws ALDOperatorException,
                        ALDProcessingDAGException
A legal method to invoke the operator and handles everything necessary to protocol the processing history. Prior to calling 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.
If hidden is true, the activation of this operator will not be visible in the processing history.

Parameters:
hidden - The activation of this operator is hidden in the processing history..
Throws:
ALDOperatorException
ALDProcessingDAGException

serializeToXmlFile

public void serializeToXmlFile(java.lang.String filename)
Serializes the operator to an XML file.

Note that all member variables, i.e. the complete state of the object at the time of serialization is saved. Only transient members are ignored.

Parameters:
filename - File where to save the data.

setParameter

public final void setParameter(java.lang.String name,
                               java.lang.Object value)
                        throws ALDOperatorException
Set the value of a parameter specified by name.

Parameters:
name - Name of the parameter to set a new value for
value - new value
Throws:
ALDOperatorException

setParametersFromXml

public java.lang.String setParametersFromXml(java.lang.String filename)
Set the parameter values as read from an Xml file. The class and package name found in the Xml are compared to the operator to set the parameters to and are required to match.

Parameters:
filename - filename of the xml file to read from
Returns:
version string found in Xml file or null if Xml file could not be properly read or class or package name check failed
See Also:
setParametersFromXml(String,String,String)

setParametersFromXml

public java.lang.String setParametersFromXml(java.lang.String filename,
                                             java.lang.String className,
                                             java.lang.String packageName)
Set the parameter values as read from an Xml file. The class and package name found in the Xml are compared to the className and packageName respectively. If one of these names is null any name in the Xml file is accepted.

Parameters:
filename - filename of the xml file to read from
className - class name expected in the Xml file or null
packageName - package name expected in the Xml file or null
Returns:
version string found in Xml file of null if Xml file could not be properly read or class or package name check failed

setVerbose

public void setVerbose(java.lang.Boolean verbose)
                throws ALDOperatorException
Set the verbose state of this opertor.

Parameters:
verbose - New verbose state
Throws:
ALDOperatorException

toString

public java.lang.String toString()
Returns a string containing printale information about this operator.

Overrides:
toString in class java.lang.Object

validate

public final void validate()
                    throws ALDOperatorException
Validates the parameters and inputs of this operator. The generic part of this validation checks that each required parameter and input is set to a non-null value. The custom part of validation is operator depended and implemented via the method validateCustom. An ALDOperatorException is thrown if either validation fails.

Throws:
ALDOperatorException

validateCustom

public void validateCustom()
                    throws ALDOperatorException
Operator specific validation of parameters and inputs. Should be overridden when extending an operator to impose specific constraints.

Throws:
ALDOperatorException

validateGeneric

public final void validateGeneric()
                           throws ALDOperatorException
Generic validation of the in and inout parameters of this operator. Validation succeeds if each required parameter and input is set to a non-null value or supplies a default value. An ALDOperatorException is thrown if validation fails.

Throws:
ALDOperatorException

writeHistory

public static void writeHistory(java.lang.Object obj,
                                java.lang.String filename)
                         throws ALDProcessingDAGException,
                                ALDOperatorException
Write the processing history if any to a graphml file. Equivalent to writeHistory(obj, filename, ALDProcessingDAG.HistoryType.COMPLETE, false)

Parameters:
obj - Object for which the history to write for.
filename - Filename to write the processing history into.
Throws:
ALDProcessingDAGException
ALDOperatorException

writeHistory

public static void writeHistory(java.lang.Object obj,
                                java.lang.String filename,
                                ALDProcessingDAG.HistoryType historyType)
                         throws ALDProcessingDAGException,
                                ALDOperatorException
Write the processing history if any to a graphml file. Equivalent to writeHistory(obj, filename, historyType, false)

Parameters:
obj - Object for which the history to write for.
filename - Filename to write the processing history into.
historyType - Type/mode of the history.
Throws:
ALDProcessingDAGException
ALDOperatorException

writeHistory

public static void writeHistory(java.lang.Object obj,
                                java.lang.String filename,
                                ALDProcessingDAG.HistoryType historyType,
                                boolean ignoreHiding)
                         throws ALDProcessingDAGException,
                                ALDOperatorException
Write the processing history if any to a graphml file.

Parameters:
obj - Object for which the history to write for.
filename - Filename to write the processing history into. (as graphml/XML file)
historyType - Type/mode of the history.
ignoreHiding - If true, hiding of opNodes is ignored.
Throws:
ALDProcessingDAGException
ALDOperatorException
See Also:
ALDPortHashAccess.writeHistory(Object,String,ALDProcessingDAG.HistoryType,boolean)

writeParametersToXml

public void writeParametersToXml(java.lang.String filename)
Write the parameter values to an xml file. Uses xstream for serialization.

Parameters:
filename - filename of the xml file to write to