Using GPServer

Summary Each GPServer object is created by the server and exists in context of a published geoprocessing service. Thus, for a GPServer object to exist, a geoprocessing service must be available to the Server Object Manager (SOM) so that the SOM can create a context for the service, and the context, in turn, can create a GPServer object for the user to use. The geoprocessing service can be created either for toolboxes containing custom or standard tools or for a Map document containing layers, including the GP tool layer. Since a service can contain multiple geoprocessing tools, a GPServer object is also said to represent a collection of geoprocessing tools.

In this topic

GPServer object workflow

The following is the workflow of an application that uses a GPServer object.
  1. Create a geoprocessing service.
  2. Connect to ArcGIS Server and create a server context using the service as shown in the following sample code.
[Java] 
String serverName = "..";
String domain = "...";
String user = "...";
String pwd = "...";
String gpServiceName = "MyToolbox";
ServerInitializer serverInit = new ServerInitializer();
serverInit.initializeServer(domain, user, pwd);
conn = new ServerConnection();
conn.connect(serverName);
System.out.println("\nConnected to " + domain + "\\" + serverName + ".");
serverContext = conn.getServerObjectManager().createServerContext(gpServiceName, 
    "GPServer");
  1. Create a GPServer object using server context. The GPServer object allows users to enumerate the set of all available tools and extract information from each tool, such as number of parameters, their types, and direction (input or output), as well as execute the tools as shown in the following code.
[Java] 
gpServer = (GPServer)serverContext.getServerObject();
  1. Retrieve and print a list of available tools in a specified toolbox as shown in the following code.
[Java] 
//Retrieve names of all available tools and models. 
IStringArray toolNames = gpServer.getToolNames();
int numberOfTools = toolNames.getCount();
System.out.println("\nNumber of tools available: " + numberOfTools);
String[] toolNames = new String[numberOfTools];
for (int i = 0; i < numberOfTools; i++){
    toolNames[i] = toolNames.getElement(i);
    System.out.println(toolNames[i]);
}
  1. Select the tool to execute, retrieve its parameter information, and initialize the parameter values as shown in the following code.
[Java] 
//Retrieve information about the first tool. 
System.out.println("Retrieving " + toolNames[i] + " info...\n");
IGPToolInfo toolInfo = gpServer.getToolInfo(toolNames[0]);
//Retrieve parameter information for the first tool. 
IGPParameterInfos paramInfos = toolInfo.getParameterInfo();
IGPValues gpValues = new GPValues(serverContext.createObject(GPValues.getClsid()));
int paramCount = paramInfos.getCount();
System.out.println("\t" + toolNames[0] + " has " + paramCount + 
    "parameters.\nInitializing input and required parameters...");
for (int i = 0; i < paramCount; i++){
    IGPParameterInfo paramInfo = paramInfos.getElement(i);
    //If the parameter is an input parameter and is required, the following is valid for a tool that takes in a feature class 
    //and linear unit as inputs. 
    Ex: Buffer tool if (paramInfo.getDirection() ==
        esriGPParameterDirection.esriGPParameterDirectionInput &&
        paramInfo.getParameterType() ==
        esriGPParameterType.esriGPParameterTypeRequired){
        if (paramInfo.getDataType().equalsIgnoreCase("GPFeatureRecordSetLayer")){
            GPFeatureRecordSetLayer fc = new GPFeatureRecordSetLayer
                (serverContext.createObject(GPFeatureRecordSetLayer.getClsid()));
            RecordSet recordSet = new RecordSet(serverContext.createObject
                (RecordSet.getClsid()));
            //*Retrieve record set from a data source and initialize above recordSet variable. That method is not shown here.*/
            //Initialize the GPFeatureRecordSetLayer.
            IGPValue value = new GPFeatureRecordSetLayer(fc);
            paramInfo.setValueByRef(value);
        }
        if (paramInfo.getDataType().equalsIgnoreCase("GPLinearUnit")){
            GPLinearUnit lu = new GPLinearUnit(serverContext.createObject
                (GPLinearUnit.getClsid()));
            lu.setUnits(esriUnits.esriMiles);
            lu.setValue(10.0);
            IGPValue value = new GPLinearUnit(lu);
            paramInfo.setValueByRef(value);
        }
    }
}

//Add the newly created value objects to the GPValues object. GPValues is used later during tool execution. 
gpValues.add(value);
System.out.println("Done.");
  1. Submit the job (tool) for execution, retrieve the job ID, and ping for status. Once the list of parameters is retrieved and all input parameters are initialized, the GPValues object must be initialized (as shown in the previous code) and the job submitted for execution as shown in the following sample code.
[Java] 
System.out.println("Executing " + toolName[0] + "...");
String jobID = gpServer.submitJob(toolName[0], gpValues);
int jobStatus = gpServer.getJobStatus(jobID);
System.out.println("\n" + toolName[0] + " submitted for execution.\nJob Status: " +
    jobStatus);

Executing geoprocessing tools on the server

There are two ways to execute a geoprocessing tool on the server.

Using GPServer.execute()

The GPServer.execute() method executes the GP tool synchronously. This method returns IGPResult, which can be used to retrieve messages and output values associated with execution of that particular geoprocessing tool. This method is recommended for geoprocessing operations that involve models where output of one tool is used as input to another tool and for operations that use small datasets and have shorter execution times.

Submitting a job

When you submit a job, the server executes the geoprocessing tool asynchronously and posts results to the jobs folder (set during ArcGIS Server post-install). When a job is submitted to the server for execution, the server creates a job ID that can be used to retrieve results. The server also creates a directory for every job it executes. This directory contains a scratch workspace for the job that is used to hold all scratch data during tool execution and results after the tool execution. The server also allows for a "delete job" operation that deletes this directory and job results; however, it's up to the user or client application to call the "delete job". If the geoprocessing tool has been published as a tool layer in an MXD file, then it will have an associated results map server. You can use this results map server to draw results that have been created on the server. This is done by passing in the job ID, whose results are to be drawn in the map description supplied to the ExportMapImage request on the results Map Server.
For more information on geoprocessing, see "Publishing Geoprocessing services" and "Publishing Map services" in the Publishing section of the ArcGIS Manager Documentation.


See Also:

Geoprocessing
Managing input and output
Using Geoprocessor