insensa.optionfilechanger
Interface OptionFileChanger

All Superinterfaces:
java.lang.Runnable
All Known Implementing Classes:
AbstractOptionFileChanger, CCopy, CEqualBreaks, CJenksOptimalBreaks, CNormalizing, CQuantileBreaks, CReplaceRasterFileValue, CVariableBreaks, TemplateCut

public interface OptionFileChanger
extends java.lang.Runnable

It is strongly recommended that you do not implement the Interface OptionFileChanger directly. Use the abstract class AbstractOptionFileChanger instead.

Author:
dennis

Method Summary
 boolean checkApproval(CRasterFileInformation rasterFile)
          Here you can check if it is correct to add this OptionFileChanger to this rasterFile.
 CRasterFileInformation getActualFile()
           
 AttributeTable getData()
           
 java.lang.String getErrorMessage()
           
 int getId()
           
 java.util.List<java.lang.String> getInfoDependencies()
           
 java.lang.String getOldFileRelativeFilePath()
           
 org.jdom.Element getOptionElement()
          Creates a new Element object that contains all Information that should be saved in a configuration file.
 java.lang.String getOptionName()
          Returns the name of the OptionFileChanger.
 int getUsableCount()
          Deprecated. should not be used since version 2.0.26
 boolean isPublic()
          Deprecated. should not be used since version 2.0.26
 boolean isUsed()
           
 void setId(int id)
          Deprecated. should not be used since version 2.0.26
 void setOldRasterFile(CRasterFileInformation oldRasterFile)
           
 void setOptionAttributes(org.jdom.Element eOption)
          Sets all attributes that are saved in the configuration file.
 void setWorkerStatus(WorkerStatus workerStatus)
           
 void write()
          This method will be executed from the ThreadPool
There are several steps that must be followed:
Get actual file
.
 
Methods inherited from interface java.lang.Runnable
run
 

Method Detail

checkApproval

boolean checkApproval(CRasterFileInformation rasterFile)
Here you can check if it is correct to add this OptionFileChanger to this rasterFile.

Parameters:
rasterFile -
Returns:

getActualFile

CRasterFileInformation getActualFile()
                                     throws java.io.IOException
Returns:
Throws:
java.io.IOException

getData

AttributeTable getData()
Returns:

getErrorMessage

java.lang.String getErrorMessage()
Returns:
An error message if there is one

getId

int getId()
Returns:

getInfoDependencies

java.util.List<java.lang.String> getInfoDependencies()
Returns:

getOptionElement

org.jdom.Element getOptionElement()
                                  throws org.jdom.IllegalDataException
Creates a new Element object that contains all Information that should be saved in a configuration file.

The configuration file is a xml file that will be saved in the "infos" directory. jdom is used to generate the file. An Element will be represented as a XML Tag in the created file

First you have to create a new Element with the name of the optionFileChanger.
This name must be the same name as you defined in the extensions.xml file
If you inherited and defined the method getOptionName correctly, you can use this function to get the name.

Example:
 Element optionElement = new Element(this.getOptionName());
 
There are TWO attributes which should ALWAYS be saved, the status of the execution (Therefore the same boolean expression that should be used in the method isUsed) and the id of the current optionFileChanger.
Both variables (used and id) are defined in

Returns:
Element with all contents that should be saved in the Configuration File AbstractOptionFileChanger.
The Integer variable id is used internally and just have to be saved and reloaded by the plugin.

Example: Assuming that used is the boolean expression
 optionElement.setAttribute("used",Boolean.toString(used));
 
Besides the used state, you can save what ever you want and it is possible to use the complex methods that jdom gives you. For example: creating subElements (child XML tags)

Note: It is strongly recommended that you define a final variable for every key you need.
The keys used here are also required in the method insensa.optionfilechanger.OptionFileChanger.setInfos and it can be fatal to use wrong keys
 private final string XML_ATTR_USED = "used";
 
Throws:
org.jdom.IllegalDataException

getOptionName

java.lang.String getOptionName()
Returns the name of the OptionFileChanger.

This MUST be the same name as defined in the extensions.xml or in EOption

Returns:
the name of the OptionFileChanger

getUsableCount

int getUsableCount()
Deprecated. should not be used since version 2.0.26

Returns:
maximum number of unused objects that can be appended to a file

isPublic

boolean isPublic()
Deprecated. should not be used since version 2.0.26

Returns:
true if the option should be settable for the user .

isUsed

boolean isUsed()
Returns:
true if the option has executed successful.

setId

void setId(int id)
Deprecated. should not be used since version 2.0.26

Parameters:
id - a unique id for this option

setOldRasterFile

void setOldRasterFile(CRasterFileInformation oldRasterFile)
Parameters:
oldRasterFile - The RasterFileInformation that will use this optionFileChanger

setOptionAttributes

void setOptionAttributes(org.jdom.Element eOption)
                         throws java.io.IOException
Sets all attributes that are saved in the configuration file.

This method is the counterpart of getOptionElement.

Parameters:
eOption - the jdom.Element which holds the attributes
Throws:
java.io.IOException - eOption holds all information that was saved.
The information that should ALWAYS stored in the configuration is the status of the execution and the id of the optionFileChanger
Example:
 
 Attribute attrUsed = element.getAttribute(XML_ATTR_USED);
 Attribute attrID = element.getAttribute(XML_ATTR_ID);
 if(attrUsed==null || attrID==null)
 throw new IOException("one ore more necessary attributes cannot be found");
 try
 {
 used=attrUsed.getBooleanValue();
 id=attrID.getIntegerValue();
 }catch (DataConversionException e)
 {
 throw new IOException(e);
 }
 
 

getOldFileRelativeFilePath

java.lang.String getOldFileRelativeFilePath()
Returns:
the relative File Path (with name) of the source RasterFile

setWorkerStatus

void setWorkerStatus(WorkerStatus workerStatus)
Parameters:
workerStatus - the WorkerStatus that should Listen to the execution progress

write

void write()
           throws java.io.IOException,
                  org.jdom.JDOMException,
                  CRasterFileException
This method will be executed from the ThreadPool
There are several steps that must be followed:
  1. Get actual file
    .

    Throws:
    java.io.IOException
    org.jdom.JDOMException
    CRasterFileException - AbstractOptionFileChanger.getActualFile()
  2. Solve dependencies
    AbstractOptionFileChanger.solveDependencies(CRasterFileInformation)
  3. Start process
  4. Create temporary file of type CRasterFileInformation
  5. Save the file under the correct filename
  6. End process


Example:
In this Example, we want to create a file as a copy of the old with every value that is <= 0.0 replace by a variable float value 0.5.

First we have to get the actual raster file. This could be the previously defined oldRasterFile but also an other file that just lies in the oldRasterFile defined as targetFile.
 CRasterFileInformation actualRasterFile = getActualRasterFile()
 
In the next step it is important to be sure that all dependencies previously defined in getInfoDependencies are available. the easiest way is to use the method AbstractOptionFileChanger.solveDependencies(CRasterFileInformation)
 solveDependencies(actualRasterFile);
 
Lets assume we need the InfoReader minMaxValues.
 CMinMaxValues minMaxValues = (CMinMaxValues)actualRasterFile.getInfoReader(EInfo.minMaxValue.toString());
 if(minMaxValues==null)
 throw new IOException("Can't solve minMaxValues")
 
If a WorkerStatus was defined we can tell it that the progress began.
 if(workerStatus!=null)
 {
 workerStatus.setProgressName("Starting replace zero");
 workerStatus.startProcess();
 }
 
Next we need to create a new temporary file as a copy of the old file with a new name
 String tmpName = getTemporaryFileName(actualRasterFile);
 CRasterFileInformation tmpRasterFile = new CRasterFileInformation(tmpName,actualRasterFile,false,false,false);
 int dataType = actualRasterFile.getBand().getDataType();
 tmpRasterFile.createNewFile(actualRasterFile, dataType, actualRasterFile.getNoDataValue());
 
 see CRasterFileInformation#CRasterFileInformation(String, CRasterFileInformation, boolean, boolean, boolean)
 and
 CRasterFile.createNewFile(insensa.CRasterFile, int, double)
 for more information
 
Now we can get Excess to the gdal functions to create the data.

Create and Write Data:
 Band band = actualRasterFile.getBand();
 Dataset tmpDataset = tmpRasterFile.getDataset();
 int xSize = band.GetXSize();
 int ySize = band.getYSize();
 float steps = 100.0F/ySize;
 float[] fData= new float[xSize];
 float readData;
 for(int i=0;i < ySize;i++)
 {
 band.ReadRaster(0,i,xSize,1,fData);
 for(int j=0;j < fData.length;j++)
 {
 readData=fData[j];
 if(readData==actualRasterFile.getNoDataValue())
 {
 }
 else
 {
 if(readData <=0.0f)
 fData[j]=0.5f;
 }
 }
 processStatus+=steps;
 if(workerStatus!=null)
 workerStatus.refreshPercentage(processStatus);
 tmpDataset.GetRasterBand(1).WriteRaster(0,i,xSize,1,fData);
 }
 tmpDataset.FlushCache();
 band.FlushCache();
 tmpDataset=null;
 band=null;
 
 
At least it is necessary to save the temporary file and set the execution status:
 saveRasterFile(tmpRasterFile, actualRasterFile);
 used=true;