de.unihalle.informatik.Alida.operator
Class ALDOperator

java.lang.Object
  extended by de.unihalle.informatik.Alida.operator.ALDOperator
All Implemented Interfaces:
ALDConfigurationValidator, ALDOperatorExecutionProgressEventListener, EventListener
Direct Known Subclasses:
ALDCalcMeanArray, ALDClusterExperiment, ALDKmeansOp, ALDNumberConverter, ALDOperatorControllable, ALDParameterTester, ALDPCAOp, ALDSummarizeArrayOp, ALDTransposeMatrix, ALDVectorNativeArrayConverter, ApplyToMatrix, FilterExperimentalDataOp, MatrixSum, NormalizeExperimentalDataOp

public abstract class ALDOperator
extends Object
implements ALDConfigurationValidator, ALDOperatorExecutionProgressEventListener

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

Nested Class Summary
static class ALDOperator.HidingMode
          Determines the visibility of an operator invocation via runOp() in the processing history.
 
Field Summary
protected  boolean completeDAG
          Does this operator prefer a complete DAG or a data dependency DAG.
 String name
          Name of the operator
protected  EventListenerList operatorExecutionEventlistenerList
          List of control event listeners attached to this class listening to ALDOperatorExecutionProgressEvent.
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 Summary
ALDOperator()
          This constructor initializes an operator.
 
Method Summary
 void addOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
          Adds a listener to this reporter.
protected  boolean fieldContained(String key)
          Does any hash table contain the key, i.e. this field?
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.
 ALDOperator.HidingMode getHidingMode()
          Return the hidingMode of this operator during execution via runOp.
 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.
 Collection<String> getParameterNames()
          Get the names of all parameters
 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 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()
          Reinitialize the field member of all parameter descriptors.
 void removeOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
          Removes a listener from this reporter.
 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 void setConstructionMode(int constructionMode)
          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.
 void setVerbose(Boolean verbose)
          Set the verbose state of this opertor.
 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

name

public String name
Name of the operator


verbose

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


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.


portHashAccess

protected static ALDPortHashAccess portHashAccess
Access to the central port hash.


versionProvider

protected ALDVersionProvider versionProvider
Instance of a class providing version information.


operatorExecutionEventlistenerList

protected transient volatile EventListenerList operatorExecutionEventlistenerList
List of control event listeners attached to this class listening to ALDOperatorExecutionProgressEvent.

Constructor Detail

ALDOperator

public 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

getConstructionMode

public static int getConstructionMode()
Return the current mode of implicit construction constructionMode.

Returns:
the constructionMode

setConstructionMode

public static void setConstructionMode(int constructionMode)
Set the 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
  • Parameters:
    constructionMode - the constructionMode to set

    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

    getName

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

    Returns:
    name of the operator

    setName

    protected void setName(String name)
    Set the name of this operator


    getHidingMode

    public ALDOperator.HidingMode getHidingMode()
    Return the hidingMode of this operator during execution via runOp.

    Returns:
    current hiding mode if operator is being executed

    setHidingMode

    public void setHidingMode(ALDOperator.HidingMode hidingMode)
    Set the hiding mode of this operator during execution via runOp.

    NOTE: A subsequent call of runOp will reset the hdingMode according to the argments of this method call.

    Parameters:
    hidingMode -

    getVersion

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

    Returns:
    version of the operator

    getALDPortHashAccessKey

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

    Returns:
    reference to the port hash access object

    getNumParameters

    public final int getNumParameters()
    Get the number of parameters

    Returns:
    number of parameters

    getInInoutNames

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

    Returns:
    names of in or inout parameters

    getInInoutNames

    public final Collection<String> getInInoutNames(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

    getOutInoutNames

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

    Returns:
    names of out or inout parameters

    getInNames

    public final Collection<String> getInNames(Boolean useRequired)
    Get the names of in parameters.

    Parameters:
    useRequired - If true return only required in parameters, if false return only not required in parameters. If null then return all in parameters.
    Returns:
    names of in parameters

    getOutNames

    public final Collection<String> getOutNames()
    Get the names of out parameters

    Returns:
    names of out parameters

    getInOutNames

    public final Collection<String> getInOutNames(Boolean useRequired)
    Get the names of inout parameters.

    Parameters:
    useRequired - If true return only required inout parameters, if false return only not required inout parameters. If null then return all inout parameters.
    Returns:
    names of in parameters

    getSupplementalNames

    public final Collection<String> getSupplementalNames()
    Get the names of supplemental parameters

    Returns:
    names of supplemental parameters

    getParameterNames

    public final Collection<String> getParameterNames()
    Get the names of all parameters

    Returns:
    collection of all parameter names

    getParameterDescriptor

    public final ALDOpParameterDescriptor getParameterDescriptor(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

    getParameter

    public Object getParameter(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

    setParameter

    public void setParameter(String name,
                             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

    readResolve

    protected Object readResolve()
    Init function for deserialized objects.

    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.

    Returns:

    reinitializeParameterDescriptors

    public void reinitializeParameterDescriptors()
    Reinitialize the field member of all parameter descriptors. This is required e.g. after de-serializing an operator object.


    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( HidingMode.VISIBLE), i.e. runs the operator as visible in the history.

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

    Throws:
    ALDOperatorException
    ALDProcessingDAGException
    See Also:
    runOp(boolean)

    runOp

    public final void runOp(ALDOperator.HidingMode hidingMode)
                     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.

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

    Parameters:
    hidingMode - Determines the visibility of this invocation in the processing history
    Throws:
    ALDOperatorException
    ALDProcessingDAGException

    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

    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

    getMissingRequiredInputs

    @Deprecated
    public List<String> getMissingRequiredInputs()
    Deprecated. 

    Returns all required IN an INOUT parameters which have a null value

    Returns:
    List of the parameter names

    unconfiguredItems

    public List<String> unconfiguredItems()
    Returns all required IN an INOUT parameters which have a null value

    Specified by:
    unconfiguredItems in interface ALDConfigurationValidator
    Returns:
    List of the parameter names

    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

    isConfigured

    public boolean isConfigured()
    Description copied from interface: ALDConfigurationValidator
    Returns true if the object is properly configured.

    Specified by:
    isConfigured in interface ALDConfigurationValidator
    Returns:

    setVerbose

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

    Parameters:
    verbose - New verbose state
    Throws:
    ALDOperatorException

    getVerbose

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

    Returns:
    Current verbose state
    Throws:
    ALDOperatorException

    readHistory

    public static void readHistory(Object obj,
                                   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)

    writeHistory

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

    Parameters:
    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)
    Throws:
    ALDProcessingDAGException
    ALDOperatorException

    writeHistory

    public static void writeHistory(Object obj,
                                    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. For handling of extensions see ALDPortHashAccess.writeHistory(Object, String, de.unihalle.informatik.Alida.operator.ALDProcessingDAG.HistoryType, boolean)
    historyType - Type/mode of the history.
    Throws:
    ALDProcessingDAGException
    ALDOperatorException

    writeHistory

    public static void writeHistory(Object obj,
                                    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 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.
    Throws:
    ALDProcessingDAGException
    ALDOperatorException
    See Also:
    ALDPortHashAccess.writeHistory(Object,String,ALDProcessingDAG.HistoryType,boolean)

    addOperatorExecutionProgressEventListener

    public void addOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
    Adds a listener to this reporter.

    Parameters:
    listener - Listener to be added.

    removeOperatorExecutionProgressEventListener

    public void removeOperatorExecutionProgressEventListener(ALDOperatorExecutionProgressEventListener listener)
    Removes a listener from this reporter.

    Parameters:
    listener - Listener to be removed.

    fireOperatorExecutionProgressEvent

    protected void fireOperatorExecutionProgressEvent(ALDOperatorExecutionProgressEvent ev)
    Sends an event of changed execution progress to all registered listeners.

    Parameters:
    ev - Event to be send to all listeners.

    print

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


    print

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

    Parameters:
    outfile - Stream to print on

    printInterface

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


    printInterface

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

    Parameters:
    outfile - Stream to print on

    print

    protected void print(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 -

    toStringVerbose

    public String toStringVerbose()
    Returns a string containing printable information about this operator including parameters.


    fieldContained

    protected boolean fieldContained(String key)
    Does any hash table contain the key, i.e. this field?


    handleOperatorExecutionProgressEvent

    public void handleOperatorExecutionProgressEvent(ALDOperatorExecutionProgressEvent event)
                                              throws ALDWorkflowException
    Description copied from interface: ALDOperatorExecutionProgressEventListener
    Method which is called on event occurence.

    Specified by:
    handleOperatorExecutionProgressEvent in interface ALDOperatorExecutionProgressEventListener
    Parameters:
    event - Event to be handled.
    Throws:
    ALDWorkflowException


    Copyright © 2010–2014 Martin Luther University Halle-Wittenberg, Institute of Computer Science, Pattern Recognition and Bioinformatics. All rights reserved.