This article will explain basic concepts of working with geoprocessing tools. You will take a preexisting tool, generate Java code for the tool, then call the code in another application. While the tool will only do a clip and a buffer, it serves to illustrate the ease with which you can carry out complex spatial operations using minimal amounts of code. The example can be found in the samples titled "geoprocessing.custom_tool." The sample includes the toolbox, which contains the tool used in this example.

ArcGIS Desktop can be used to actually create the tool. You can also chain multiple tools together to reduce the number of calls to geoprocessing, but more important, you can encapsulate a workflow into a tool that can be easily reused.

The first step is to produce Java code for the tool. There are two methods to create this wrapper code: You can use the command line or use a tool built into Eclipse. Open a command prompt in any directory and enter the following command:

		java -cp "%ARCGISHOME%\java\lib\arcobjects.jar" com.esri.arcgis.geoprocessing.gen.ToolboxGenerator

This will show you the command line parameters for generating Java code for a tool. To generate the code for the toolbox in the sample, you execute the following command:

		java -cp "%ARCGISHOME%\java\lib\arcobjects.jar" com.esri.arcgis.geoprocessing.gen.ToolboxGenerator -b Toolbox -p C:/<Directory Location Of the toolbox> -n <the.package.name.for.the.classes> -s C:/toolbox/output

Notice that the tbx extension is left of the toolbox. After successful completion of the command, inside the toolbox/output directory you will find a directory structure corresponding to a package structure you specified for -n with a Java class of ClipBuffer inside. The toolbox name is always appended to the end of the package name. You can now import this Java class into an IDE and begin to work with it like any of the other tools.

To generate the wrappers from Eclipse you need to install the ESRI Eclipse Plug-ins. Please see the Eclipse Plug-ins documentation for further instructions.

The tool and its code

Below is a graphical representation of the tool for which you just generated Java code. It takes an InputFeatureClass and clips it with a ClipFeatureClass. After the clip, an intermediate dataset will be created from the results of the clip operation. This data will then be buffered to create a feature class, FinalOutput. All the circles that have P's next to them will be parameters for the tool. Therefore, the user of the tool will have to set the InputFeatureClass, the ClipFeatureClass, the Buffer distance, and the name for the output FeatureClass. Because the states_Clip dataset is marked as intermediate in the tool, it will be deleted when the tool is finished executing.

The Java class generated from this tool has the following interface:

You will notice there is a default constructor that takes the four required parameters as well as setters and getters for each property. You use this tool just as you would any of the other Java classes for the default toolboxes. Since there are FeatureClasses and a field that could be a number or a field name for required parameters, all these parameters are set by passing in objects of the appropriate type. Because you have generated the Java code for the tool, you can augment the Javadoc so that users can have a better idea of what are appropriate parameters to pass in to your tool.

To execute this tool from your Java code, you will need to add the toolbox to the geoprocessor by calling the addToolbox method and giving the full path to the location of the *.tbx file.

The following code is required to call the tool:

		clipBuffer = new ClipBuffer("0.5", outputLocation+"/clipbuff_out.shp", inFileGDB+ File.separator + "center", inFileGDB + File.separator +"states");
		gp.execute(clipBuffer, null);

With two lines of code, you have replaced what would have been significant amounts of ArcObjects code. The other benefit is that you can distribute your Java class and toolbox to other developers and they will have access to all the same functionality.

This demo should not only show the ease of creating Java classes for custom tools but more importantly the ability to encapsulate complicated spatially enabled business logic with very little Java code. The authoring of the logic can be done with a tool that is focused on spatial solutions, ArcGIS Desktop, but you can then use that logic from any of your Java-based applications. In conclusion, you can use ArcObjects programming and geoprocessing together to create Java applications that carry out advanced spatial analysis and data management.

If the underlying tool changes but none of the parameters change, you do not need to regenerate the Java classes.

Since ArcGIS Desktop is now able to run ArcGIS Java programs, you can have you ArcGIS Desktop user generate the Java classes for you. They need to have Java installed on their machine to be able to use the command line usage given above. Have them send you the Java code and the toolbox, and you should be ready to develop using their tool. This allows for a separation of the people responsible for creating the business rules and those writing the Java application.

The license that your application code needs to check out has to match the highest level of any of the tools used in your custom tool. For example, if your custom tool uses a tool that requires an ArcInfo license, then your application needs to check out an ArcInfo license.