Eachhttp://edndoc.esri.com/arcobjects/9.2/Java/java/working_java_api/geoprocessing/runninggptool.html
geoprocessing tool has a fixed set of parameters that provides the tool with the information it needs for execution. Tools usually have input parameters that define the dataset or datasets that will typically be used to generate new output data. Parameters have several important properties:
- Name: Each tool parameter has a unique name.
- Type: The type of data expected, such as feature class, integer, string, and raster.
- Required: Either a value must be provided for a parameter or it is optional.
When a tool is used in a program, its parameter values must be correctly set so it can execute when the program is run. The documentation of each tool clearly defines its parameters and properties. Once a valid set of parameter values are provided, the tool is ready to be executed.
Parameters are specified either as strings, objects, or native types for simple parameters. An example of a native type is the number of neighbors parameters on the CalculateDistanceBand tool. Strings are text values that uniquely identify a parameter value, such as a path to a dataset or a keyword.
Most tool parameters can be specified as a simple string. However, complex parameters such as a spatial reference, may be easier to specify with an object. In the following code example, the required parameters for the Buffer tool are defined. In this case, strings are used to define the input, the output, and the buffer distance properties of Buffer so the call to the tool is easier to read.
Be aware that the syntax for specifying fields in query expressions is different for different data formats. Some of the most commonly encountered differences are below.
- For ArcSDE, the field names are not wrapped, for example, MY_FIELD.
- For file or personal geodatabases the field names are wrapped in square brackets, for example, [MY_FIELD].
- For all others, the field names are wrapped in double quotes, for example, "MY_FIELD".
- Access uses '*' and '?' as string wildcards rather than '%' and '_' in all other formats
The Execute method below uses null reference instead of an ITrackCancel object. The ITrackCancel interface provides access to properties and methods that determine if a cancellation has been executed by the user, and also allows developers to specify what actions constitute a cancellation.
// Initialize the Geoprocessor
Geoprocessor GP = new Geoprocessor();
Buffer bufferTool = new Buffer("c:/data/usa.gdb/wind.shp", "c:/data/usa.gdb/bufferedWind.shp", "distance");
GP.execute(bufferTool, null);
Below are the system toolbox names and their namespaces:
- Analysis Tools? com.esri.arcgis.geoprocessing.tools.analysistools
- Conversion Tools? com.esri.arcgis.geoprocessing.tools.conversiontools
- Data Management Tools? com.esri.arcgis.geoprocessing.tools.datamanagementtools
- 3D Analyst Tools? com.esri.arcgis.geoprocessing.tools.analyst3dtools
- Cartography Tools? com.esri.arcgis.geoprocessing.tools.cartographytools
- Coverage Tools? com.esri.arcgis.geoprocessing.tools.coveragetools *
- Geocoding Tools? com.esri.arcgis.geoprocessing.tools.geocodingtools
- Geostatistical Analyst Tools? com.esri.arcgis.geoprocessing.tools.geostatisticalanalysttools
- Linear Referencing Tools? com.esri.arcgis.geoprocessing.tools.linearreferencingtools
- Multidimension Tools? com.esri.arcgis.geoprocessing.tools.multidimensiontools
- Network Analyst Tools? com.esri.arcgis.geoprocessing.tools.networkanalysttools
- Spatial Analyst Tools? com.esri.arcgis.geoprocessing.tools.spatialanalysttools
- Spatial Statistics Tools? com.esri.arcgis.geoprocessing.tools.spatialstatisticstools
- Tracking Analyst Tools?com.esri.arcgis.geoprocessing.tools.trackinganalysttools
* (Only available with a ArcInfo Workstation install and not available on Linux)
Running Custom Geoprocessing Tools
In addition to using the existing tools and toolboxes provided by ESRI, it is also possible to execute your custom tools such as model tools and script tools which exist in custom toolboxes. Using the IDE integration framework built in to Eclipse or the command line, you can generate a geoprocessing assembly to represent any custom toolbox. For instructions please see the documentation on wrapping a custom tool.
Executing a Tool by Name
It is not a prerequisite to generate a geoprocessing assembly to represent your custom toolbox. There is an alternative way to use the Execute method on the Geoprocessor. The Execute method is overloaded and has an additional parameters which allows you to execute a tool by specifying the tool name, the parameters to the tool, and the ITrackCancel object.
Here is an example of executing a model tool called CaluateBestPath located in the Bestpath toolbox:
// Initialize the Geoprocessor
Geoprocessor GP = new Geoprocessor();
// Add the BestPath toolbox
GP.addToolbox("c:/SanDiego/BestPath.tbx");
// Generate the array of parameters
VarArray parameters = new VarArray();
parameters.add("c:/SanDiego/source.shp");
parameters.add("c:/SanDiego/destination.shp");
parameters.add("c:/SanDiego/bestpath.shp");
// Execute the Model tool by name
GP.execute("CalculateBestPath", parameters, null);
See Also:
wrapping a custom tool
Executing Geoprocessing Server Tools
With ArcGIS 9.2 Desktop and Engine, you can now execute geoprocessing tools that have been published on an ArcGIS server. Server tools can be accessed and executed the same as custom tools. First, you must add the custom toolbox by generating a geoprocessing toolbox assembly to represent the toolbox or by adding the custom toolbox using the AddToolbox method.
Toolboxes can be published on a local area network (LAN) or published as a web service on the internet. To access the geoprocessing server tools you must add the toolbox. Here are examples for adding toolboxes published on an ArcGIS server using the AddToolbox method:
// Add the BestPath toolbox published on a LAN // Entered as server name;folder/toolbox gp.addToolbox(攆lame7;SanDiego/BestPath"); // Add the BestPath toolbox published as a Geoprocessing web service // Entered as Web service;folder/toolbox gp.addToolbox(攈ttp://flame7:8399/arcgis/services;SanDiego/BestPath");
Toolboxes published on the server may contain tools that require you to enter the input parameter values by specifying the path to the data or, contain tools that require the user to choose from a list of inputs referencing layers in a map document on the ArcGIS server. See ArcGIS Server and Geoprocessing for further information about publishing geoprocessing tools to an ArcGIS server.
Here are two examples illustrating how to executing server tools:
- Execute a tool by reference. The input parameters reference layers in a map document which contains the toolbox and tools.
// Intialize the Geoprocessor Geoprocessor gp = new GeoProcessor(); // Add the BestPath toolbox gp.addToolbox("http://flame7:8399/arcgis/services;GP/Bestpathtoolbox"); // Inputs reference layers in a map document on the server. ArrayList parameters = new ArrayList(); parameters.add("source"); parameters.add("destination"); // Execute the server tool by reference IGeoProcessorResult result; result = gp.execute("CalculateBestPath", parameters, null); - Execute a tool by value. The input parameters are shapefiles on a local drive.
// Intialize the Geoprocessor GeoProcessor gp = new GeoProcessor(); // Add the BestPath toolbox gp.addToolbox("http://flame7:8399/arcgis/services;GP/Bestpathtoolbox"); // Input values are data on a local drive. ArrayList parameters = new ArrayList; parameters.add("C:\\sandiego\\source.shp"); parameters.add("C:\\sandiego\\destination.shp"); // Execute the server tool by reference IGeoProcessorResult result; result = gp.execute("CalculateBestPath", parameters, null);
Geoprocessing Results
All geoprocessing tools generate results. The Execute method returns an IGeoProcessorResult object which manages the results. The result object is necessary for supporting geoprocessing with ArcGIS server. This result object will have the return value of a tool when executed; it will return the status of a job on the server, it will return the result id, and provide the geoprocessing messages.
Here is an example of executing a server tool and getting it's status and messages:
// Intialize the Geoprocessor
GeoProcessor gp = new GeoProcessor();
// Add the BestPath toolbox
gp.addToolbox("http://flame7:8399/arcgis/services;GP/Bestpathtoolbox");
// Input values are data on a local drive.
ArrayList parameters = new ArrayList();
parameters.add("C:\\sandiego\\source.shp");
parameters.add("C:\\sandiego\\destination.shp");
// Execute the server tool by reference
IGeoProcessorResult result;
result = gp.execute("CalculateBestPath", parameters, null);
while (result.getStatus() == esriJobStatus.esriJobSucceeded){
for(int i = 0; i <= result.getMessageCount() - 1; i++){
System.out.println(result.getMessageCount());
}