quoggles.boxes
Interface IBox

All Known Subinterfaces:
IOutputBox
All Known Implementing Classes:
Box, NormalOutput_Box

public interface IBox

Interface for boxes. Provides methods to set the input(s), execute the code of the box and get its output(s).


Method Summary
 void execute()
          Executes the box, i.e. calculates the output from the input.
 IBoxRepresentation getGraphicalRepresentation()
          If your subclass has any parameters, you will probably have to design your own representation and implement this method for example as follows: if (iBoxGRep == null || !
 java.lang.String getId()
          Returns a unique id.
 int[] getInputTypes()
          Implement this method to specify the types for the input(s) of the box.
 org.graffiti.graph.Node getNode()
          Returns the node that holds this box.
 int getNumberOfInputs()
          Returns the number of inputs this box expects.
 int getNumberOfOutputs()
          Returns the number of outputs this box provides.
 java.lang.Object getOutputAt(int index)
          Returns the ith output.
 java.lang.Object[] getOutputs()
          Returns the output array of the box.
 int[] getOutputTypes()
          Implement this method to specify restricted types for the output(s) of the box.
 org.graffiti.plugin.parameter.Parameter[] getParameters()
          Returns the array of currently set parameters.
 boolean hasBeenExecuted()
          Returns true iff the box's execute() method has been called since the creation of the box or the last call to reset.
 boolean ignoreBox()
          Gets the value previously set by setIgnoreBox(boolean) or returns false if not yet set.
 boolean isInputSet()
          Returns true iff all inputs have been set.
 boolean isInputSetAt(int index)
          Returns true iff the input at the given index has been set.
 boolean needsQueryRunner()
          Should return true if the box needs the queryRunner field to be set.
 void reset()
          Reset the box: Inputs will not be set, ...
 void reset(int index)
          States that the input at the given index is no longer valid.
 void setBoxNumber(int boxNumber)
          Set the number of the box.
 void setCurrentNodesTodo(java.util.Stack nodesTodo)
          Sets the stack of nodes that still have to be processed via a call to runQuery.
 void setCurrentResult(java.util.List res)
          Sets the list (representing the result table) that the last call to runQuery returned.
 void setDefaultParameters()
          Important only if the subclass has any parameters.
 void setIgnoreBox(boolean ignore)
          Specifies whether or not a box should be ignored by any query processing (possibly because it has already been executed as part of a sub query).
 void setInputAt(java.lang.Object input, int index)
          Sets the input at the specified index.
 void setInputs(java.lang.Object[] inputs)
          Checks if the number of inputs is correct and sets the inputs.
 void setNode(org.graffiti.graph.Node node)
          Sets the node that holds this box.
 void setParameters(org.graffiti.plugin.parameter.Parameter[] pars, boolean fromRep)
          Sets the parameters of this box.
 void setQueryRunner(RunQuery qr)
          Set the object that has a runQuery method to be called for the execution of the predicate sub query.
 

Method Detail

setBoxNumber

public void setBoxNumber(int boxNumber)
Set the number of the box. Used for identification purposes.

Parameters:
boxNumber - a number identifying the box

getInputTypes

public int[] getInputTypes()
Implement this method to specify the types for the input(s) of the box. The size of the returned array must be consistent with the return value of getNumberOfInputs.

Returns:
an int array whose size gives the number of inputs. The entries specify the type of the inputs. This uses constants defined in quoggles.constants.ITypeConstants.
See Also:
ITypeConstants

getNumberOfInputs

public int getNumberOfInputs()
Returns the number of inputs this box expects.

Returns:
the number of inputs this box expects

setInputs

public void setInputs(java.lang.Object[] inputs)
               throws InvalidInputException
Checks if the number of inputs is correct and sets the inputs. Also must ensure that a call to execute will no longer throw an InputNotSetException.

Parameters:
inputs - the inputs of the box
InvalidInputException

setInputAt

public void setInputAt(java.lang.Object input,
                       int index)
                throws InvalidInputException
Sets the input at the specified index.

Parameters:
input - the input to be set at the given index
index - the index of the input to set
InvalidInputException

isInputSet

public boolean isInputSet()
Returns true iff all inputs have been set.

Returns:
true iff all inputs have been set.

isInputSetAt

public boolean isInputSetAt(int index)
Returns true iff the input at the given index has been set.

Parameters:
index - between zero and getNumberOfInputs()-1
Returns:
true if the input has been set at the given index

execute

public void execute()
             throws QueryExecutionException
Executes the box, i.e. calculates the output from the input. Should be overridden and called first by subclasses.

Throws:
InputNotSetException - if the inputSet flag indicates the no input has been set for this box.
maybe - other QueryExecutionExceptions.
QueryExecutionException

hasBeenExecuted

public boolean hasBeenExecuted()
Returns true iff the box's execute() method has been called since the creation of the box or the last call to reset.

Returns:
true if the box has been executed and its outputs are ready

getNumberOfOutputs

public int getNumberOfOutputs()
Returns the number of outputs this box provides.

Returns:
the number of outputs this box provides

getOutputTypes

public int[] getOutputTypes()
Implement this method to specify restricted types for the output(s) of the box. The size of the returned array must be consistent with the return value of getNumberOfOutputs.

Returns:
an int array whose size gives the number of outputs. The entries specify the type of the outputs. This uses constants defined in quoggles.constants.ITypeConstants.
See Also:
ITypeConstants

getOutputs

public java.lang.Object[] getOutputs()
                              throws BoxNotExecutedException
Returns the output array of the box. Throws exception if the box's execute method has not been called.

Returns:
the outputs of the box
BoxNotExecutedException

getOutputAt

public java.lang.Object getOutputAt(int index)
                             throws BoxNotExecutedException
Returns the ith output.

Returns:
the ith output of the box
BoxNotExecutedException

setDefaultParameters

public void setDefaultParameters()
Important only if the subclass has any parameters. It sets the values of the parameters that are displayed first time the user sees this box.


setParameters

public void setParameters(org.graffiti.plugin.parameter.Parameter[] pars,
                          boolean fromRep)
Sets the parameters of this box. This method should (the implementation of Box does it) call setParameters on the representation of this box. To avoid updating several times, this is not done when the given flag fromRep is true since then the call has originated from the representation.

Parameters:
pars - the parameters to be set
fromRep - true if called from the box's representation

getParameters

public org.graffiti.plugin.parameter.Parameter[] getParameters()
Returns the array of currently set parameters.

Returns:
the parameters of the box

getId

public java.lang.String getId()
Returns a unique id.

Returns:
a String identifying the box

getGraphicalRepresentation

public IBoxRepresentation getGraphicalRepresentation()
If your subclass has any parameters, you will probably have to design your own representation and implement this method for example as follows: if (iBoxGRep == null || !(iBoxGRep instanceof MYOWNBOX_Rep)) { iBoxGRep = new MYOWNBOX_Rep(this); } return iBoxGRep;

Returns:
the graphical representation of the box. Should be the same object each time the method is called.

reset

public void reset()
Reset the box: Inputs will not be set, ...


reset

public void reset(int index)
States that the input at the given index is no longer valid.

Parameters:
index - the index of the input that should be marked as invalid

setIgnoreBox

public void setIgnoreBox(boolean ignore)
Specifies whether or not a box should be ignored by any query processing (possibly because it has already been executed as part of a sub query).

Parameters:
ignore - true iff the box should not be executed

ignoreBox

public boolean ignoreBox()
Gets the value previously set by setIgnoreBox(boolean) or returns false if not yet set.

Returns:
true if the box should be ignored

needsQueryRunner

public boolean needsQueryRunner()
Should return true if the box needs the queryRunner field to be set.

Returns:
true if an object implementing the RunQuery interface should be passed to this box

setQueryRunner

public void setQueryRunner(RunQuery qr)
Set the object that has a runQuery method to be called for the execution of the predicate sub query. Only used if needsQueryRunner() returns true.

Parameters:
qr - an object that has a runQuery(...) method
See Also:
needsQueryRunner()

setCurrentResult

public void setCurrentResult(java.util.List res)
Sets the list (representing the result table) that the last call to runQuery returned. Only boxes that run sub queries need this information. They use that as the result to pass on to the sub query executor.

Parameters:
res - the last result of a call to runQuery(...)

setCurrentNodesTodo

public void setCurrentNodesTodo(java.util.Stack nodesTodo)
Sets the stack of nodes that still have to be processed via a call to runQuery. Only boxes that run sub queries need this information. They pass it on to the sub query executor.

Used to prevent multiple execution of boxes that can be reached from a high level and is executed within a lower level (sub query).

Parameters:
nodesTodo - the stack of nodes that still need to be processed

setNode

public void setNode(org.graffiti.graph.Node node)
Sets the node that holds this box.

Parameters:
node - the node that holds this box.

getNode

public org.graffiti.graph.Node getNode()
Returns the node that holds this box.

Returns:
the node that holds this box