es.unex.sextante.core
Class GeoAlgorithm

java.lang.Object
  extended by es.unex.sextante.core.GeoAlgorithm
Direct Known Subclasses:
ModelAlgorithm

public abstract class GeoAlgorithm
extends java.lang.Object

A class defining a geo-algorithm

Author:
Victor Olaya volaya@unex.es

Constructor Summary
GeoAlgorithm()
           
 
Method Summary
 boolean adjustRasterOutputExtent()
          This method sets the raster output extent according to input layers, in case it hasn't been set.
abstract  void defineCharacteristics()
          This method should be overridden and used to specify the parameters needed by the GeoAlgorithm, using the corresponding methods of the ParametersSet object.
 boolean execute(ITaskMonitor task, OutputFactory outputFactory)
          This method should be used to execute the algorithm once the parameters have been assigned.
 boolean generatesLayers()
          Returns true if the algorithms generates new layers
 boolean generatesUserDefinedRasterOutput()
           
 java.lang.String[] getAlgorithmAsCommandLineSentences()
          Returns the command line expression that would create this instance of the algorithm
 java.lang.String getCommandLineHelp()
          Returns a string containing the command line usage of the algorithm
 java.lang.String getCommandLineName()
           
 GridExtent getGridExtent()
           
 java.lang.String getGroup()
           
 java.lang.String getMessages()
          Returns a string with the messages produced by the algorithm
 java.lang.String getName()
           
 GeoAlgorithm getNewInstance()
           
 int getNumberOfLineVectorLayers()
           
 int getNumberOfOutputLayers()
          Returns the number of new layers generated by the algorithm
 int getNumberOfParameters()
           
 int getNumberOfPointVectorLayers()
           
 int getNumberOfPolygonLayers()
           
 int getNumberOfRasterLayers()
           
 int getNumberOfTables()
           
 int getNumberOfVectorLayers()
           
 OutputObjectsSet getOutputObjects()
           
 ParametersSet getParameters()
           
 java.util.HashMap getProcessMetadata()
          Returns a map with metadata entries.
 boolean hasCorrectParameterValues()
          Returns true if the algorithm parameters have correct values.
 boolean isDeterminatedProcess()
           
 boolean isSuitableForModelling()
           
 boolean meetsDataRequirements(java.lang.Object[] objs)
          Returns true if the algorithm could be executed with the given data objects.
 boolean meetsRasterRequirements(java.lang.Object[] objs)
          Returns false if there are not enough raster data in the given array to run the algorithm
 boolean meetsTableRequirements(java.lang.Object[] objs)
          Returns false if there are not enough table objects in the given array to run the algorithm
 boolean meetsVectorRequirements(java.lang.Object[] objs)
          Returns false if there are not enough vector data in the given array to run the algorithm
abstract  boolean processAlgorithm()
          This method should implement the algorithm itself, using the values of the parameters and processing them.
 boolean requiresIndividualRasterLayers()
          Returns true if the algorithm requires raster layers as individual input (i.e. not as a multiple input)
 boolean requiresIndividualVectorLayers()
          Returns true if the algorithm requires vector layers as individual input (i.e. not as a multiple input)
 boolean requiresLineVectorLayers()
          Returns true if the algorithm requires line vector layers to run
 boolean requiresMultipleRasterBands()
          Returns true if the algorithm requires raster bands as multiple input (i.e. the parameter set contains a multiple input parameter of type band)
 boolean requiresMultipleRasterLayers()
          Returns true if the algorithm requires raster layers as multiple input
 boolean requiresMultipleTables()
          Returns true if the algorithm requires tables layers as multiple input
 boolean requiresMultipleVectorLayers()
          Returns true if the algorithm requires vector layers as multiple input
 boolean requiresNonDataObjects()
           
 boolean requiresPoints()
          Returns true if the algorithm requires point coordinates to run
 boolean requiresPointVectorLayers()
          Returns true if the algorithm requires point vector layers to run
 boolean requiresPolygonVectorLayers()
          Returns true if the algorithm requires polygon vector layers to run
 boolean requiresRasterLayers()
          Returns true if the algorithm requires raster layers to run
 boolean requiresTableFields()
          Returns true if the algorithm requires table field layers to run
 boolean requiresTables()
          Returns true if the algorithm requires raster layers to run
 boolean requiresVectorLayers()
          Returns true if the algorithm requires vector layers to run
 void setGeneratesUserDefinedRasterOutput(boolean bGeneratesRasterOutput)
          Use this method to indicate that the algorithm generates new raster layers and the user can select their grid extent.
 void setGridExtent(GridExtent gridExtent)
          Sets a new grid extent that will be used to create new raster layer if the algorithm generates that kind of output
 void setGroup(java.lang.String sGroup)
          Sets the name of the group this algorithm belongs to.
 void setIsDeterminatedProcess(boolean bDeterminated)
          Use this method to indicate that the algorithm is determinated (i.e. the number of steps to complete it is known)
 void setName(java.lang.String sName)
          Sets the algorithm name.
 void setOutputObjects(OutputObjectsSet ooSet)
          sets a new set of output objects
 void setParameters(ParametersSet parameters)
          sets a new set of parameters for the algorithm
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

GeoAlgorithm

public GeoAlgorithm()
Method Detail

defineCharacteristics

public abstract void defineCharacteristics()
This method should be overridden and used to specify the parameters needed by the GeoAlgorithm, using the corresponding methods of the ParametersSet object. Also, output objects must be added, so SEXTANTE knows in advance which outputs will be generated by the algorithm. See the addOutputXXXX family of methods (addOutputRasterLayer(java.lang.String, java.lang.String, int, java.lang.String, es.unex.sextante.dataObjects.IRasterLayer), addOutputVectorLayer(java.lang.String, java.lang.String, int, java.lang.String, es.unex.sextante.dataObjects.IVectorLayer), etc.)


execute

public boolean execute(ITaskMonitor task,
                       OutputFactory outputFactory)
                throws GeoAlgorithmExecutionException
This method should be used to execute the algorithm once the parameters have been assigned.

Parameters:
task - a ITaskMonitor to track the progress of the execution. If is null, a @see SilentTaskMonitor will be used.
outputFactory - The output factory to use to generate new data objects
Returns:
true if the algorithm was correctly executed. False if it was canceled
Throws:
GeoAlgorithmExecutionException

getProcessMetadata

public java.util.HashMap getProcessMetadata()
Returns a map with metadata entries. It will return an empty map if the process has not been executed yet.

Returns:
the metadata of the process.

processAlgorithm

public abstract boolean processAlgorithm()
                                  throws GeoAlgorithmExecutionException
This method should implement the algorithm itself, using the values of the parameters and processing them.

Returns:
true if the algorithm was correctly executed. False if it was canceled.
Throws:
GeoAlgorithmExecutionException - if there were problems during algorithm execution

adjustRasterOutputExtent

public boolean adjustRasterOutputExtent()
This method sets the raster output extent according to input layers, in case it hasn't been set. When the algorithm requires just one raster input layer, its extent is used. When more than one are required, the minimum extent needed to cover them all is used, along with the minimum cellsize of them all.

Returns:
false if there are no raster layers or they are not set.

getName

public java.lang.String getName()
Returns:
The algorithm name. Might return different strings depending on the current SEXTANTE language

setName

public void setName(java.lang.String sName)
Sets the algorithm name. Use this in the defineCharacteristics() method Use @see Sextante.getText(String) to support internationalization

Parameters:
sName - the name of the algorithm

getGroup

public java.lang.String getGroup()
Returns:
The group to which the algorithm belongs. Might return different strings depending on the current SEXTANTE language

setGroup

public void setGroup(java.lang.String sGroup)
Sets the name of the group this algorithm belongs to. Use this in the defineCharacteristics() method Use @see Sextante.getText(String) to support internationalization

Parameters:
sGroup - the name of the group

getParameters

public ParametersSet getParameters()
Returns:
the set of parameters needed to run the algorithm

setParameters

public void setParameters(ParametersSet parameters)
sets a new set of parameters for the algorithm

Parameters:
parameters - the new set of parameters

getGridExtent

public GridExtent getGridExtent()
Returns:
The grid extent that will be used to create new raster layer if the algorithm generates that kind of output

setGridExtent

public void setGridExtent(GridExtent gridExtent)
Sets a new grid extent that will be used to create new raster layer if the algorithm generates that kind of output

Parameters:
gridExtent - the new grid extent

getMessages

public java.lang.String getMessages()
Returns a string with the messages produced by the algorithm

Returns:
a string with messages produced by the algorithm

requiresNonDataObjects

public boolean requiresNonDataObjects()
Returns:
true if the algorithm requires parameters other than input layers or tables

getNumberOfParameters

public int getNumberOfParameters()
Returns:
The number of parameters needed to run the algorithm

getNumberOfRasterLayers

public int getNumberOfRasterLayers()
Returns:
The number of raster layers needed to run the algorithm

getNumberOfVectorLayers

public int getNumberOfVectorLayers()
Returns:
The number of vector layer needed to run the algorithm

getNumberOfPointVectorLayers

public int getNumberOfPointVectorLayers()
Returns:
The number of point vector layer needed to run the algorithm

getNumberOfLineVectorLayers

public int getNumberOfLineVectorLayers()
Returns:
The number of line layer needed to run the algorithm

getNumberOfPolygonLayers

public int getNumberOfPolygonLayers()
Returns:
The number of polygon vector layer needed to run the algorithm

getNumberOfTables

public int getNumberOfTables()
Returns:
The number of tables needed to run the algorithm

generatesUserDefinedRasterOutput

public boolean generatesUserDefinedRasterOutput()
Returns:
true if the algorithm generates new raster layers with user defined dimensions

setGeneratesUserDefinedRasterOutput

public void setGeneratesUserDefinedRasterOutput(boolean bGeneratesRasterOutput)
Use this method to indicate that the algorithm generates new raster layers and the user can select their grid extent. When creating the corresponding panel for the algorithm, it will contain a "raster output" tab, so the user can define the extent he prefers for the raster layers to be created

Parameters:
bGeneratesRasterOutput - true if the algorithm generates new raster layers

setIsDeterminatedProcess

public void setIsDeterminatedProcess(boolean bDeterminated)
Use this method to indicate that the algorithm is determinated (i.e. the number of steps to complete it is known)

Parameters:
bDeterminated - true if it is a determinated algorithm

isDeterminatedProcess

public boolean isDeterminatedProcess()
Returns:
true if the algorithm is determinated (i.e. the number of steps to complete it is known)

getOutputObjects

public OutputObjectsSet getOutputObjects()
Returns:
the set of output objects generated by the algorithm

setOutputObjects

public void setOutputObjects(OutputObjectsSet ooSet)
sets a new set of output objects

Parameters:
ooSet - the new set of output objects

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getCommandLineName

public java.lang.String getCommandLineName()
Returns:
the command line name of the algorithm

getNewInstance

public GeoAlgorithm getNewInstance()
                            throws java.lang.InstantiationException,
                                   java.lang.IllegalAccessException
Returns:
a new instance of the algorithm
Throws:
java.lang.InstantiationException
java.lang.IllegalAccessException

isSuitableForModelling

public boolean isSuitableForModelling()
Returns:
true if the algorithm is suitable for a modeling process. This should be based on how well-defined the outputs are. If the number of output layers cannot be known in advance, then this method should return false

generatesLayers

public boolean generatesLayers()
Returns true if the algorithms generates new layers

Returns:
true if the algorithms generates new layers

getNumberOfOutputLayers

public int getNumberOfOutputLayers()
Returns the number of new layers generated by the algorithm

Returns:
the number of new layers generated by the algorithm

getCommandLineHelp

public java.lang.String getCommandLineHelp()
Returns a string containing the command line usage of the algorithm

Returns:
a string containing the command line usage of the algorithm

getAlgorithmAsCommandLineSentences

public java.lang.String[] getAlgorithmAsCommandLineSentences()
Returns the command line expression that would create this instance of the algorithm

Returns:
A command line expression representing this algorithm

requiresVectorLayers

public boolean requiresVectorLayers()
Returns true if the algorithm requires vector layers to run

Returns:
true if the algorithm requires vector layers to run
See Also:
ParametersSet.requiresVectorLayers()

requiresIndividualVectorLayers

public boolean requiresIndividualVectorLayers()
Returns true if the algorithm requires vector layers as individual input (i.e. not as a multiple input)

Returns:
true if the algorithm requires vector layers as individual input

requiresPolygonVectorLayers

public boolean requiresPolygonVectorLayers()
Returns true if the algorithm requires polygon vector layers to run

Returns:
true if the algorithm requires polygon vector layers to run
See Also:
ParametersSet.requiresPolygonVectorLayers()

requiresLineVectorLayers

public boolean requiresLineVectorLayers()
Returns true if the algorithm requires line vector layers to run

Returns:
true if the algorithm requires line vector layers to run
See Also:
ParametersSet.requiresLineVectorLayers()

requiresPointVectorLayers

public boolean requiresPointVectorLayers()
Returns true if the algorithm requires point vector layers to run

Returns:
true if the algorithm requires point vector layers to run
See Also:
ParametersSet.requiresVectorLayers()

requiresRasterLayers

public boolean requiresRasterLayers()
Returns true if the algorithm requires raster layers to run

Returns:
true if the algorithm requires raster layers to run
See Also:
ParametersSet.requiresVectorLayers()

requiresIndividualRasterLayers

public boolean requiresIndividualRasterLayers()
Returns true if the algorithm requires raster layers as individual input (i.e. not as a multiple input)

Returns:
true if the algorithm requires raster layers as individual input

requiresMultipleRasterLayers

public boolean requiresMultipleRasterLayers()
Returns true if the algorithm requires raster layers as multiple input

Returns:
true if the algorithm requires raster layers as multiple input

requiresMultipleVectorLayers

public boolean requiresMultipleVectorLayers()
Returns true if the algorithm requires vector layers as multiple input

Returns:
true if the algorithm requires vector layers as multiple input

requiresMultipleTables

public boolean requiresMultipleTables()
Returns true if the algorithm requires tables layers as multiple input

Returns:
true if the algorithm requires tables layers as multiple input

requiresMultipleRasterBands

public boolean requiresMultipleRasterBands()
Returns true if the algorithm requires raster bands as multiple input (i.e. the parameter set contains a multiple input parameter of type band)

Returns:
true if the algorithm requires raster bands as multiple input

requiresTables

public boolean requiresTables()
Returns true if the algorithm requires raster layers to run

Returns:
true if the algorithm requires raster layers to run
See Also:
ParametersSet.requiresVectorLayers()

requiresTableFields

public boolean requiresTableFields()
Returns true if the algorithm requires table field layers to run

Returns:
true if the algorithm requires table fields to run
See Also:
ParametersSet.requiresTableFields()

requiresPoints

public boolean requiresPoints()
Returns true if the algorithm requires point coordinates to run

Returns:
true if the algorithm requires point coordinates to run
See Also:
ParametersSet.requiresPoints()

meetsRasterRequirements

public boolean meetsRasterRequirements(java.lang.Object[] objs)
Returns false if there are not enough raster data in the given array to run the algorithm

Parameters:
objs - an array of available data objects
Returns:
false if the algorithm requires more raster layers than the ones in the data objects array. True if they suffice

meetsVectorRequirements

public boolean meetsVectorRequirements(java.lang.Object[] objs)
Returns false if there are not enough vector data in the given array to run the algorithm

Parameters:
objs - an array of available data objects
Returns:
false if the algorithm requires more (or different, i.e other shape type) vector layers than the ones in the data objects array. True if they suffice

meetsTableRequirements

public boolean meetsTableRequirements(java.lang.Object[] objs)
Returns false if there are not enough table objects in the given array to run the algorithm

Parameters:
objs - an array of available data objects
Returns:
false if the algorithm requires more tables than the ones in the data objects array. True if they suffice

meetsDataRequirements

public boolean meetsDataRequirements(java.lang.Object[] objs)
Returns true if the algorithm could be executed with the given data objects.

Parameters:
objs - an array of available data objects
Returns:
true if the algorithm could be executed with the given data objects.

hasCorrectParameterValues

public boolean hasCorrectParameterValues()
Returns true if the algorithm parameters have correct values.

Returns:
true if the algorithm parameters have correct values