edu.udo.cs.miningmart.m4
Interface Step

All Superinterfaces:
GraphicalM4Object, M4Data, M4Object
All Known Implementing Classes:
Step

public interface Step
extends GraphicalM4Object

Version:
$Id: Step.java,v 1.6 2006/04/11 14:10:12 euler Exp $
Author:
Timm Euler, Daniel Hakenjos

Method Summary
 void addDatabaseObjectToTrash(java.lang.String objectName, java.lang.String schemaName, java.lang.String objectType)
          Helper method to store the information about a database object in the trash index
 void addParameterTuple(Parameter par)
          Adds a parameter to this step's parameter list on tuple level.
 void addPredecessor(Step step)
           
 void addSuccessor(Step step)
          This method should only be called from the method Case.addStepDependency(Step, Step)!
 void addToTrash(M4Data m4data)
          This method should only be called by the compiler after a new M4 object has been created by calling a constructor.
 boolean belongsToChainOrSubChain(Chain theChain)
          This method returns TRUE if this Step belongs to the given Chain, or to a direct or indirect subchain of the given Chain.
 boolean checkInputParameterEntries()
          This method checks, for the current set of values of input parameters in this step, whether they fulfill all parameter contraints.
 boolean checkOutputParameterEntries()
          This method checks, for the current set of values of output parameters in this step, whether they fulfill all parameter contraints.
 Step copy(Case newCase, Chain newChain)
           
 void createOutput(OpParam theOpParam, java.util.Collection theNames)
          This method must only be called if no output objects existed for this Step before!
 Parameter createParameterTuple(java.lang.String name, ParameterObject object, long number, int loopNumber, java.lang.String type)
          Creates a Parameter that will be connected to this Step.
 Parameter createValueParameterTuple(java.lang.String value, java.lang.String datatype, java.lang.String name, long number, int loopNumber, java.lang.String type)
          Creates a Parameter and a Value that will be connected to this Step.
 void deleteDbTrash()
          This method takes care of deleting trash objects from the business data schema.
 void deleteM4Trash()
          This method realizes the M4Compiler's garbage collection on the objects created during compilation of this Step.
 boolean dependencyExists(Chain toChain)
          Checks if this step has a successor among any of the steps in the given chain, including steps in any direct or indirect subchain of the given chain.
 java.util.Collection getAllInputConcepts()
          This method returns all concepts that are input concept to this step's operator, even those that are attached to an input relation but not modelled by an input parameter.
 java.util.Collection getAllInputRelations()
          Returns all relations that are a parameter object of an input parameter of this Step.
 java.util.Collection getAllPredecessors()
           
 long getCaseId()
          Getter method.
 java.util.Collection getCrossReferences()
           
 java.util.Collection getInputConceptsThatAreParameters()
          This method returns all concepts that are input concept to this step's operator.
 BaseAttribute[][] getKeysOfRelationshipAssertion()
          This method checks if this Step creates a relationship from or to its output concept.
 int getLoopCount()
          Getter method.
 java.util.Collection getM4Trash()
          Active getter for the compiler's M4 Trash information.
 java.lang.String getMultiStepCondition()
          Getter method.
 long getNumber()
          Getter method.
 Concept getOutputConcept()
          Returns the output concept of this step, if it exists, and NULL otherwise.
 java.util.Collection getParameter(OpParam theOpParam, int loopNr)
          Returns the instance of the given OpParam that is currently set in this Step.
 ParamDict getParameterDictionary(boolean expectingAllParamsToExist)
          Returns the parameter dictionary of the step.
 Parameter getParameterTuple(java.lang.String name, int loopNr)
          Return the parameter (tuple) of this step with the given name and loop number.
 java.util.Collection getParameterTuples()
          Active getter for the parameters of this Step in tuple-wise form (not aggregated by OpParam arrays!).
 java.util.Collection getPossibleConceptsForParam(OpParam opParam)
          Whenever an input of type BaseAttribute or MultiColumnFeature is expected the possible Concepts the Features may come from are explicitly given by constraints.
 java.util.Collection getPossibleInputConcepts()
          This method finds all Concepts that are either of type DB or are created as an output concept by a Step that precedes this Step in the chain.
 java.util.Collection getResultingDataModel()
          Returns a collection of concepts; these concepts represent the data model that the current Case produced up to this Step.
 java.util.Collection getSuccessors()
          Active getter for this Step's successors.
 Case getTheCase()
          Getter method.
 Chain getTheChain()
          Getter method.
 Operator getTheOperator()
          Active getter method.
 boolean hasPredecessorOutsideChain()
          This method returns TRUE if this Step has a direct predecessor that does not belong to the same chain, nor one of its subchains.
 boolean hasSuccessorOutsideChain()
          This method returns TRUE if this Step has a direct successor that does not belong to the same chain, nor one of its subchains.
 boolean inputChangeCanAffectOutput(OpParam theOpParam)
          Returns TRUE iff a change to the given input OpParam can have any effect on the output parameters of this Step.
 boolean isCompiled()
          After a Step has been successfully compiled a flag in the M4 database is set, which is removed by the next garbage collection.
 boolean isContainedInInputConcept(OpParam outputFeature)
          This method must only be called for an output feature.
 boolean isRelationallyValid()
           
 boolean isVisible(Feature theFeature)
          This method returns TRUE iff the given Feature may be displayed in the input concept, or in a list of Features to choose from for a parameter.
 void removeAllParameterTuples()
           
 void removeParameter(java.lang.String parName)
           
 boolean removeParameterTuple(Parameter par)
          Removes a parameter from this step's parameter list on tuple level.
 void removePredecessor()
          Removes the link to the specified Predecessor.
 boolean removeSuccessor(Step step)
          Removes a Step from this Step's Collection of dependent Steps.
 boolean removeSuccessor(java.lang.String name)
          Removes a Step from this Step's Collection of dependent Steps.
 void renameOutput(OpParam theOpParam, java.util.Collection theNames)
          This method changes the names of the output parameter objects; the latter are assumed to exist.
 void setCompiled()
          This method may only be called by the control structure!
 void setLoopCount(int lc)
          Setter method.
 void setMultiStepCondition(java.lang.String msc)
          Setter method.
 void setNumber(long nr)
          Setter method.
 void setParameter(OpParam theOpParam, java.util.Collection theParameterObjects, int loopNr)
          Sets the parameter specified by the given OpParam.
 void setTheCase(Case myCase)
          Setter method.
 void setTheChain(Chain chain)
          Setter method.
 void setTheOperator(Operator theOp)
          Setter method.
 void updateOutput(OpParam theOpParam)
          This method must only be called if any input parameter of this Step was changed.
 boolean usesLoopsForCoordination()
          This method returns TRUE if the coordinated parameters in this step (ab)use the loop mechanism for their coordination.
 
Methods inherited from interface edu.udo.cs.miningmart.m4.GraphicalM4Object
getPoint, setPoint
 
Methods inherited from interface edu.udo.cs.miningmart.m4.M4Data
deleteSoon, getDocumentation, getValidName, isDirty, isWaitingForDelete, setDocumentation
 
Methods inherited from interface edu.udo.cs.miningmart.m4.M4Object
doPrint, doPrint, equals, executeBusinessSingleValueSqlRead, executeBusinessSingleValueSqlReadL, executeBusinessSqlRead, executeBusinessSqlWrite, executeM4SingleValueSqlRead, executeM4SingleValueSqlReadL, executeM4SqlRead, executeM4SqlWrite, getCasePrintObject, getId, getM4Db, getM4ObjectFromCache, getName, getNextM4SequenceValue, isNew, load, print, putM4ObjectToCache, replaceSpacesInName, setId, setName
 

Method Detail

getTheOperator

public Operator getTheOperator()
Active getter method.

Returns:
the M4 operator object related to this Step

setTheOperator

public void setTheOperator(Operator theOp)
Setter method. There is no back-reference from Operator, so we do not need another primitive setter.

Parameters:
theOp - The new operator

getTheChain

public Chain getTheChain()
Getter method.

Returns:
the Chain of this Step

setTheChain

public void setTheChain(Chain chain)
                 throws M4Exception
Setter method.

Parameters:
chain - The new chain
Throws:
M4Exception

getCaseId

public long getCaseId()
Getter method.

Returns:
the id

getNumber

public long getNumber()
Getter method.

Returns:
the number

setTheCase

public void setTheCase(Case myCase)
                throws M4Exception
Setter method.

Parameters:
myCase - The new case
Throws:
M4Exception

setNumber

public void setNumber(long nr)
Setter method.

Parameters:
nr - the new step number

getLoopCount

public int getLoopCount()
Getter method.

Returns:
the loop count

getMultiStepCondition

public java.lang.String getMultiStepCondition()
Getter method.

Returns:
the multistep condition

addParameterTuple

public void addParameterTuple(Parameter par)
                       throws M4Exception
Adds a parameter to this step's parameter list on tuple level.

Parameters:
par - the Parameter object representing the parameter tuple
Throws:
M4Exception

removeParameterTuple

public boolean removeParameterTuple(Parameter par)
                             throws M4Exception
Removes a parameter from this step's parameter list on tuple level.

Parameters:
par - the Parameter object representing the parameter tuple
Returns:
true iff the object was part of the parameter list and could be removed
Throws:
M4Exception

removeAllParameterTuples

public void removeAllParameterTuples()
                              throws M4Exception
Throws:
M4Exception

removeParameter

public void removeParameter(java.lang.String parName)
                     throws M4Exception
Throws:
M4Exception

dependencyExists

public boolean dependencyExists(Chain toChain)
                         throws M4Exception
Checks if this step has a successor among any of the steps in the given chain, including steps in any direct or indirect subchain of the given chain.

Parameters:
toChain - the given chain
Returns:
TRUE iff this step has a successor among any of the steps in the given chain.
Throws:
M4Exception

setLoopCount

public void setLoopCount(int lc)
                  throws M4Exception
Setter method.

Parameters:
lc - the new loop count
Throws:
M4Exception

setMultiStepCondition

public void setMultiStepCondition(java.lang.String msc)
Setter method.

Parameters:
msc - The new multistep condition

getAllInputConcepts

public java.util.Collection getAllInputConcepts()
                                         throws M4Exception
This method returns all concepts that are input concept to this step's operator, even those that are attached to an input relation but not modelled by an input parameter.

Throws:
M4Exception

getInputConceptsThatAreParameters

public java.util.Collection getInputConceptsThatAreParameters()
                                                       throws M4Exception
This method returns all concepts that are input concept to this step's operator. (For Join and other operators, there can be more than one input concept.) Note that concepts attached to an input relation are not returned!

Throws:
M4Exception

getAllInputRelations

public java.util.Collection getAllInputRelations()
                                          throws M4Exception
Returns all relations that are a parameter object of an input parameter of this Step.

Returns:
a collection of relations
Throws:
M4Exception

getKeysOfRelationshipAssertion

public BaseAttribute[][] getKeysOfRelationshipAssertion()
                                                 throws M4Exception
This method checks if this Step creates a relationship from or to its output concept. If no, null is returned. If yes, it checks whether the output concept and its features have been created yet. If yes, it returns the BaseAttributes that form the keys of the relationship in a two-dimensional array.

Returns:
a two-dimensional array of the BaseAttributes that are the keys of the relationship created by this Step, or null
Throws:
M4Exception

getOutputConcept

public Concept getOutputConcept()
                         throws M4Exception
Returns the output concept of this step, if it exists, and NULL otherwise.

Returns:
a concept or NULL
Throws:
M4Exception

getTheCase

public Case getTheCase()
Getter method.

Returns:
this step's case

getParameterTuples

public java.util.Collection getParameterTuples()
                                        throws M4Exception
Active getter for the parameters of this Step in tuple-wise form (not aggregated by OpParam arrays!).

Returns:
Returns a Collection of Parameter objects
Throws:
M4Exception

getSuccessors

public java.util.Collection getSuccessors()
                                   throws M4Exception
Active getter for this Step's successors.

Returns:
Collection of dependent Step objects
Throws:
M4Exception

addSuccessor

public void addSuccessor(Step step)
                  throws M4Exception
This method should only be called from the method Case.addStepDependency(Step, Step)! Please use that method instead of this one, because it also efficiently reorders the steps! Adds a Step to this Step's Collection of dependent Steps.

Parameters:
step - the Step to add
Throws:
M4Exception

removeSuccessor

public boolean removeSuccessor(Step step)
                        throws M4Exception
Removes a Step from this Step's Collection of dependent Steps.

Parameters:
step - the Step to remove
Returns:
true iff the Step was found in the Collection and could be successfully removed
Throws:
M4Exception

removeSuccessor

public boolean removeSuccessor(java.lang.String name)
                        throws M4Exception
Removes a Step from this Step's Collection of dependent Steps.

Parameters:
name - the name of the step to remove
Returns:
true iff the Step was found in the Collection and could be successfully removed
Throws:
M4Exception

getParameterDictionary

public ParamDict getParameterDictionary(boolean expectingAllParamsToExist)
                                 throws M4Exception
Returns the parameter dictionary of the step. It contains the parameter tuples that are currently known to this steps in aggregated form. A boolean parameter is used to specify whether the calling method expects all parameters of this step (as specified by this step's operator's OpParams) to exist already.

Parameters:
expectingAllParamsToExist - If true, the caller expects the step to be fully parameterised.
Returns:
ParamDict object for the current step
Throws:
M4Exception

getCrossReferences

public java.util.Collection getCrossReferences()
                                        throws M4Exception
Returns:
a Collection of Step to Step dependencies for sequentializing all Steps before writing updates to the database.
Throws:
M4Exception

getM4Trash

public java.util.Collection getM4Trash()
                                throws M4Exception
Active getter for the compiler's M4 Trash information.

Returns:
a Collection of M4Data objects created by the M4 compiler that have to be removed before this Step can be compiled anew.
Throws:
M4Exception

addToTrash

public void addToTrash(M4Data m4data)
                throws M4Exception
This method should only be called by the compiler after a new M4 object has been created by calling a constructor.

Parameters:
m4data - the M4Data object to be added to the table M4TRASH_T for being garbage collected before compiling this Step or any of its predecessors.
Throws:
M4Exception

deleteM4Trash

public void deleteM4Trash()
                   throws M4Exception
This method realizes the M4Compiler's garbage collection on the objects created during compilation of this Step.

Throws:
M4Exception

addDatabaseObjectToTrash

public void addDatabaseObjectToTrash(java.lang.String objectName,
                                     java.lang.String schemaName,
                                     java.lang.String objectType)
                              throws M4Exception
Helper method to store the information about a database object in the trash index

Throws:
M4Exception

deleteDbTrash

public void deleteDbTrash()
                   throws M4Exception
This method takes care of deleting trash objects from the business data schema.

Throws:
M4Exception

isCompiled

public boolean isCompiled()
                   throws M4Exception
After a Step has been successfully compiled a flag in the M4 database is set, which is removed by the next garbage collection. This method checks, if this flag is set.

Returns:
true iff this Step has been successfully compiled and no garbage collection involving this Step has been run afterwards.
Throws:
M4Exception

setCompiled

public void setCompiled()
                 throws M4Exception
This method may only be called by the control structure! It marks this Step as successfully compiled. This information is used when it is checked for succeeding Steps, if all of the dependent resources are already available.

Throws:
M4Exception

usesLoopsForCoordination

public boolean usesLoopsForCoordination()
                                 throws M4Exception
This method returns TRUE if the coordinated parameters in this step (ab)use the loop mechanism for their coordination.

Returns:
TRUE iff parameters of the coordinated parameter groups should be read and set using positive loop numbers.
Throws:
M4Exception

isRelationallyValid

public boolean isRelationallyValid()

copy

public Step copy(Case newCase,
                 Chain newChain)
          throws M4Exception
Throws:
M4Exception

addPredecessor

public void addPredecessor(Step step)
                    throws M4Exception
Throws:
M4Exception

getAllPredecessors

public java.util.Collection getAllPredecessors()
                                        throws M4Exception
Throws:
M4Exception

getResultingDataModel

public java.util.Collection getResultingDataModel()
                                           throws M4Exception
Returns a collection of concepts; these concepts represent the data model that the current Case produced up to this Step.

Returns:
a collection of concepts
Throws:
M4Exception

belongsToChainOrSubChain

public boolean belongsToChainOrSubChain(Chain theChain)
                                 throws M4Exception
This method returns TRUE if this Step belongs to the given Chain, or to a direct or indirect subchain of the given Chain.

Parameters:
theChain - the given Chain
Returns:
TRUE iff this Step belongs to the given Chain or one of its (direct or indirect) subchains.
Throws:
M4Exception

hasPredecessorOutsideChain

public boolean hasPredecessorOutsideChain()
                                   throws M4Exception
This method returns TRUE if this Step has a direct predecessor that does not belong to the same chain, nor one of its subchains.

Returns:
TRUE if a predecessor of this Step exists outside this Step's Chain
Throws:
M4Exception

hasSuccessorOutsideChain

public boolean hasSuccessorOutsideChain()
                                 throws M4Exception
This method returns TRUE if this Step has a direct successor that does not belong to the same chain, nor one of its subchains.

Returns:
TRUE if a successor of this Step exists outside this Step's Chain
Throws:
M4Exception

getParameterTuple

public Parameter getParameterTuple(java.lang.String name,
                                   int loopNr)
                            throws M4Exception
Return the parameter (tuple) of this step with the given name and loop number.

Parameters:
name - the Name
loopNr - the loop number as in M4
Throws:
M4Exception

getParameter

public java.util.Collection getParameter(OpParam theOpParam,
                                         int loopNr)
                                  throws M4Exception
Returns the instance of the given OpParam that is currently set in this Step. The returned Collection contains instances of ParameterObjects. For single parameters, only one object is contained in the collection; for array parameters, there can be more; for optional parameters, the collection can be empty.

Parameters:
theOpParam - an OpParam object specifying the parameter to be returned
loopNr - the loop index for this parameter (ignored for non-loopable parameters)
Returns:
a Collection of ParameterObjects
Throws:
M4Exception

setParameter

public void setParameter(OpParam theOpParam,
                         java.util.Collection theParameterObjects,
                         int loopNr)
                  throws M4Exception
Sets the parameter specified by the given OpParam. Depending on the type of parameter, the given Collection can contain exactly one (for a single parameter), or several (for an array parameter), ParameterObjects.

Parameters:
theOpParam - an OpParam object specifying the parameter to be set
theParameterObjects - a Collection of ParameterObjects
loopNr - the loop index for this parameter (ignored for non-loopable parameters)
Throws:
M4Exception

checkInputParameterEntries

public boolean checkInputParameterEntries()
                                   throws M4Exception
This method checks, for the current set of values of input parameters in this step, whether they fulfill all parameter contraints. If not, an exception is thrown whose message can be used by the GUI as an error message for the user. The user can then correct the corresponding parameter entry, then this method should be called again, until it returns TRUE and does not throw an exception. The method can be called before the output is created, as it will only check the validity of the input parameter values.

Returns:
TRUE iff the current set of input parameters is valid for this step, in terms of all constraints holding for the parameters.
Throws:
M4Exception - An exception carrying a meaningful error message, intended to direct the user to improve the parameter settings.

checkOutputParameterEntries

public boolean checkOutputParameterEntries()
                                    throws M4Exception
This method checks, for the current set of values of output parameters in this step, whether they fulfill all parameter contraints. If not, an exception is thrown whose message can be used by the GUI as an error message for the user. The user can then correct the corresponding parameter entry, then this method should be called again, until it returns TRUE and does not throw an exception.

Returns:
TRUE iff the current set of output parameters is valid for this step, in terms of all constraints holding for the parameters.
Throws:
M4Exception - An exception carrying a meaningful error message, intended to direct the user to improve the parameter settings.

isVisible

public boolean isVisible(Feature theFeature)
                  throws M4Exception
This method returns TRUE iff the given Feature may be displayed in the input concept, or in a list of Features to choose from for a parameter. If FALSE is returned, it means that the given Feature is constructed by a FeatureConstruction operator in a different branch of the chain of steps, thus the Feature has no meaning for this step.

Parameters:
theFeature - The feature for which visibility is tested
Returns:
TRUE iff the feature can be used in this Step
Throws:
M4Exception

createOutput

public void createOutput(OpParam theOpParam,
                         java.util.Collection theNames)
                  throws M4Exception
This method must only be called if no output objects existed for this Step before! This method creates the output concept or output feature(s) for this step. What is to be created is specified by the given OpParam object. The name(s) for the new object(s) are given in the collection theNames. If there are both output concept AND output feature(s), please call this method FIRST with the concept!

Parameters:
theOpParam - the OpParam object specifying which output parameter is meant
theNames - a Collection of Strings giving the name(s) for the new object(s)
Throws:
M4Exception

renameOutput

public void renameOutput(OpParam theOpParam,
                         java.util.Collection theNames)
                  throws M4Exception
This method changes the names of the output parameter objects; the latter are assumed to exist. If the input parameters of the step have also changed, call the method updateOutput before this one.

Parameters:
theOpParam - the OpParam object specifying which output parameter is meant
theNames - a Collection of Strings giving the new name(s)
Throws:
M4Exception

updateOutput

public void updateOutput(OpParam theOpParam)
                  throws M4Exception
This method must only be called if any input parameter of this Step was changed. It ensures consistency of the output parameter objects with the input parameter objects. If the name of the output parameter has also changed, call the method renameOutput afterwards.

Parameters:
theOpParam - the OpParam object specifying which output parameter is meant
Throws:
M4Exception

inputChangeCanAffectOutput

public boolean inputChangeCanAffectOutput(OpParam theOpParam)
                                   throws M4Exception
Returns TRUE iff a change to the given input OpParam can have any effect on the output parameters of this Step. For example, if the NewRangeMin-parameter of a Scaling-Step is changed then the output parameters are not affected. In contrast, if the number of features selected in a manual FeatureSelection step changes, then the output concept must be updated.

Parameters:
theOpParam - an input OpParam of the operator of this step
Returns:
TRUE if the output may have to be updated if the input was updated
Throws:
M4Exception

getPossibleConceptsForParam

public java.util.Collection getPossibleConceptsForParam(OpParam opParam)
                                                 throws M4Exception
Whenever an input of type BaseAttribute or MultiColumnFeature is expected the possible Concepts the Features may come from are explicitly given by constraints. These constraints refer to the parameter names as used for the OpParam objects. This method returns a Collection of such OpParam names for input Concept parameters, e.g. "TheInputConcept".

Parameters:
opParam - the OpParam parameter referring to an input feature.
Returns:
a Collection consisting of the OpParam names (Strings) of the Concepts this feature is allowed to be selected from (due to an 'IN' constraint).
Throws:
M4Exception

getPossibleInputConcepts

public java.util.Collection getPossibleInputConcepts()
                                              throws M4Exception
This method finds all Concepts that are either of type DB or are created as an output concept by a Step that precedes this Step in the chain.

Returns:
a Collection of Concepts
Throws:
M4Exception

isContainedInInputConcept

public boolean isContainedInInputConcept(OpParam outputFeature)
                                  throws M4Exception
This method must only be called for an output feature. It is checked whether the output feature is constrained to be IN the input concept.

Parameters:
outputFeature - the OpParam representing the output feature
Returns:
TRUE iff the outputFeature's name should be selected from the names of the features of the input concept; FALSE if any new name can be given to the outputFeature.
Throws:
M4Exception

removePredecessor

public void removePredecessor()
                       throws M4Exception
Removes the link to the specified Predecessor.

Throws:
M4Exception

createParameterTuple

public Parameter createParameterTuple(java.lang.String name,
                                      ParameterObject object,
                                      long number,
                                      int loopNumber,
                                      java.lang.String type)
                               throws M4Exception
Creates a Parameter that will be connected to this Step. The name of the Parameter must be unique for this Step.

Parameters:
name - The name for the new Parameter.
object - The parameter object. It must be a Concept, Relationship , BaseAttribute, MultiColumnFeature or Value
number - the parameter number
loopNumber - the loop number
type - the parameter type. Possible values are Parameter.TYPE_INPUT or Parameter.TYPE_OUTPUT
Returns:
The new Parameter object.
Throws:
M4Exception

createValueParameterTuple

public Parameter createValueParameterTuple(java.lang.String value,
                                           java.lang.String datatype,
                                           java.lang.String name,
                                           long number,
                                           int loopNumber,
                                           java.lang.String type)
                                    throws M4Exception
Creates a Parameter and a Value that will be connected to this Step. The name of the Parameter must be unique for this Step. A Value object will be created that will be connected to the created Parameter.

Parameters:
value - The value for the Value Object.
datatype - The datatype for the value. Use one of the predefined types available for @link DomainDatatype
name - The name for the new Parameter.
number - the parameter number
loopNumber - the loop number
type - the parameter type. Possible values are Parameter.TYPE_INPUT or Parameter.TYPE_OUTPUT
Returns:
The new Parameter object.
Throws:
M4Exception


Copyright © 2001-2005