GeoprocessingResource

Geoprocessing resources are only supported with ArcGIS Server data sources.  Using ArcGIS Desktop and Server products, you can publish a tool or model in a toolbox as a geoprocessing (GP) service by itself or associated with a map document.  Once published, GP services can be added as a resource to a Web ADF application using a GeoprocessingResourceManager.  Each GP service can contain one or more models or tools, each regarded as a "server task" or "server tool".

Implemented by : ArcGIS Server Local, ArcGIS Server Internet

Functionality types created: IGeoprocessingFunctionality

As with other ArcGIS Server resources, geoprocessing resources are split between an internet and local implementation, but share a common geoprocessing functionality.  Since ArcGIS Server data source implementations in the Web ADF utilize the ArcGIS Server SOAP API, communication between a GeoprocessingResource and a GP service uses Values objects and a proxy.  The GeoprocessingResourceLocal class provides access to server context via the ServerContextInfo.ServerContext property.  Server context may be utilized in some situations - see the Discussion on Geoprocessing in ArcGIS Server for more details.



GeoprocessingFunctionality: IGeoprocessingFunctionality

The Web ADF Common API defines a set of generic geoprocessing types to work explicitly with geoprocessing functionality.  You'll use these types when working with methods on IGeoprocessingFunctionality to execute GP tasks on the server.   Behind the scenes, these Common API types must map to data source specific types (ArcGIS Server types), which must also map to geoprocessing types originally defined in the model or tool.   Geoprocessing types defined in the model are the most comprehensive.  ArcGIS Server SOAP API types expose a subset of those available in a model or tool.  The Common API types must work with the data source specific types in the ArcGIS Server SOAP API. 

The table below defines the data types that may be defined in a geoprocessing model or tool under the heading "Published Data Types".  Of these data types, a subset can be utilized within a published GP service.  Whether using the ArcGIS Server ArcObjects API (IGPServer) or the SOAP API (GPServerProxy) a set of data types, prefixed with "GP", are available for both server task inputs and outputs.  The Web ADF Common API maps generic input and output types, also prefixed with "GP", to data source implementation types - in the case of ArcGIS Server, to the GPServer data types.  When working within the Web ADF, the Common API GP data types can be utilized with IGeoprocessingFunctionality methods.

• Published geoprocessing types are defined while editing the model in ArcCatalog. 
• ArcGIS Server ArcObjects geoprocessing types are included in the ESRI.ArcGIS.Geoprocessing library. 
• ArcGIS Server SOAP geoprocessing types are included in the ESRI.ArcGIS.ADF.ArcGISServer library.   ArcGIS Server implementations for both local and internet data sources in the Web ADF use these types.
• Web ADF Common API geoprocessing types used by IGeoprocessingFunctionality are included in the ESRI.ArcGIS.ADF.Web.DataSources library.
  

A number of generic methods are available on the IGeoprocessingFunctionality interface.  Note that server tasks within a GP service can function synchronously or asynchronously, depending on how the service was configured.   Synchronous execution means that the caller (client) executes a server task and waits for a response before proceeding.  Asynchronous execution means that the caller submits a job and continues to function.  The client is then responsible for checking with the GP service to determine if the job was finished, using a unique job id.  If finished, the results can be retrieved and processed by the client.    

Property or Method	Description
GetExecutionType()	Returns the type of server task execution: asynchronous or synchronous
GetTask()	Return a GPToolInfo object associated with a server task
GetTaskNames()	Return a string array of server task names available in a GP service
GetTasks()	Return an array of GPToolInfo objects, each associated with a server task in a GP service.

ArcGIS Server implementation of IGeoprocessingFunctionality includes some methods to work with geoprocessing resource provided by ArcGIS Server. The table below lists methods that will commonly be used to interact with ArcGIS Server GP services:

Property or Method	Description
Execute()	Returns a GPResult object with the task execution results\outputs.  Designed for synchronous use.
SubmitJob()	Submits a job for processing by a server task.  Returns a job id to check status.  Designed for asynchronous use.
GetJobStatus()	Returns a JobStatus enumeration to determine the current state of the job being processed.  Designed for asynchronous use.
GetJobResult()	Returns a GPResult object with task execution results\output.   Designed for asynchronous use.
GetJobMessages()	Returns a JobMessage array for verbose information about the status of job processing on the server.

The sample code below illustrates how to work with an ArcGIS Server geoprocessing functionality.  Note that although a geoprocessing resource item has been added to a GeoprocessingResourceManager control, it is not initialized, unless used by a GeoprocessingTask control.  As a result, a GeoprocessingFunctionality must be created and initialized first.  Once initialized, you can get the server task you want to work with and discover the input types to determine what it needs to execute.  In this example, an asynchronous server task is used, so we will submit a job for processing and check periodically for completion.  The server task name is "BufferPoints" and is designed to accept two inputs: the points to buffer (Feature Set) and the buffer distance (Linear Unit).

[C#]

IGeoprocessingResource igp = GeoprocessingResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality agp = 
    (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality)
    igp.CreateFunctionality(typeof(ESRI.ArcGIS.ADF.Web.DataSources.IGeoprocessingFunctionality), null);
agp.Initialize();
    
string taskname = "BufferPoints";

Get the server task to work with via the ArcGIS Server GeoprocessingFunctionality. Iterate through the input and output parameters.

[C#]

ESRI.ArcGIS.ADF.Web.DataSources.GPToolInfo gpti = agp.GetTask(taskname); 

ESRI.ArcGIS.ADF.Web.DataSources.GPParameterInfo[] paramInfos = gpti.ParameterInfo;

ESRI.ArcGIS.ADF.Web.DataSources.GPParameterInfo paramInfo;
for (int i = 0; i < paramInfos.Length; i++)
{
    paramInfo = paramInfos[i];
    System.Diagnostics.WriteLine(paramInfo.Name);
}

The first input is the Feature Set contains the points to buffer. Since we're working with the ArcGIS Server implementation of the Common API, we will use the Common API GP types. Using the table above, we can see that a Feature Set input in a published model is a GPFeatureGraphicsLayer type in the Web ADF. This type provides a wrapper for an ArcGIS Server GPFeatureRecordSet and has the ability to be utilized as a Web ADF graphics layer.   In this example, a Map control contains a graphics resource with a graphics layer that contains a set of Web ADF points.  We need to iterate through the graphics layer in the map and add the points to the FeatureGraphicsLayer that is part of the GPFeatureGraphicsLayer input to the GP server task. 

[C#]

GPFeatureGraphicsLayer gfl = (GPFeatureGraphicsLayer) paramInfos[0].Value;
FeatureGraphicsLayer glayer = gfl.Layer;

IEnumerable gfc = Map1.GetFunctionalities();
ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource gResource = null;
foreach (IGISFunctionality gfunc in gfc)
{
    if (gfunc.Resource.Name == "Points")
    {
        gResource = (ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource)gfunc.Resource;
        break;
    }
}
if (gResource == null)
{ throw new Exception("No Points in Graphics layer to buffer."); }

ESRI.ArcGIS.ADF.Web.Display.Graphics.ElementGraphicsLayer player = (ElementGraphicsLayer)gResource.Graphics.Tables[0];

foreach (DataRow dr in player.Rows)
{
    ESRI.ArcGIS.ADF.Web.Geometry.Point pnt = (ESRI.ArcGIS.ADF.Web.Geometry.Point)player.GeometryFromRow(dr);
    glayer.Add(pnt);
}

The second input is the buffer distance.  The Common API type for a Linear Unit in the published GP server task is a GPLinearUnit.  A GPLinearUnit has two properties to store the value (or distance) and the unit.  In the code below, both are maintained as session variables and converted into the appropriated type.

[C#]

GPLinearUnit gpLU = new GPLinearUnit();

string bufferunits = (string)Page.Session["BufferUnits"];
ESRI.ArcGIS.ADF.Web.DataSources.Units adf_bufferunits;
adf_bufferunits = (ESRI.ArcGIS.ADF.Web.DataSources.Units)Enum.Parse(typeof(ESRI.ArcGIS.ADF.Web.DataSources.Units), bufferunits, true);
        
gpLU.Units = adf_bufferunits;

string strbd = (string)Session["BufferDistance"];
float bufferdistance;
if (!Single.TryParse(strbd, out bufferdistance))
{
    bufferdistance = 0.0F;
}

gpLU.Value = bufferdistance;

Once the input properties are set, they are packaged in a GPValue array.  The order of the parameters in the GP server task must match the order in the GPValue array.  Calling the SubmitJob() method on the GP server task and passing the input values returns a unique job id.  The job id should be stored in a sufficient manner for the application.  If the results of the GP process are expected before the end of the user session, a session variable on the Web server or JavaScript variable on the client may be appropriate.  If the job id needs to be persisted across sessions, a Web application accessible database may provide the best option.  

[C#]

GPValue[] gpvalues = new GPValue[2];
gpvalues[0] = gfl;
gpvalues[1] = gpLU;
string JobID;        
JobID = agp.SubmitJob(taskname, gpvalues); 		
			

The following code checks to determine if a submitted GP server task has completed. If so, it will get the results.  Note that the geoprocessing functionality must be initialized again. The JobStatus enumeration provides a number of options for determining the state of a GP process.   


[C#]

IGeoprocessingResource igp = GeoprocessingResourceManager1.GetResource(0);
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality agp =
    (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.GeoprocessingFunctionality)
    igp.CreateFunctionality(typeof(ESRI.ArcGIS.ADF.Web.DataSources.IGeoprocessingFunctionality), null);
agp.Initialize();

if (agp.GetJobStatus(JobID) != JobStatus.Succeeded)
{ 
    return;
}

Once the GP server task has completed, the task results are available. In the following code, the GPResult object returned from the completed server task maintains a GPValue array. Since this example expects a single output parameter, the buffer geometry, we can retrieve the first item in the GPValue array.   The output type in the published GP server task is a Feature Class.  The Web ADF Common API wraps this type as a GPFeatureGraphicsLayer.   As a result, is contains a Web ADF FeatureGraphicsLayer which can easily be rendered in a graphics resource within a map.

[C#]

GPResult gpr = agp.GetJobResult(taskname, JobID, parameternames, false);

GPValue[] gpvs = gpr.Values;

GPFeatureGraphicsLayer gfl = (GPFeatureGraphicsLayer)gpvs[0];
FeatureGraphicsLayer glayer = gfl.Layer;			
			

Comparing general spatial operations with geoprocessing

ArcGIS Server (and in some cases the Web ADF) provide the ability to perform general spatial operations such as using a spatial filter to select features, buffering feature geometry or creating a feature class.   ArcGIS Server provides access to a geoprocessing framework to enhance interaction with general spatial operations as geoprocessing tools or tasks.  It does this by enabling the consolidation of multiple operations into a model and providing a common set of data type inputs and outputs for cross-application compatibility.  Multiple models, or tasks, can be combined in a single geoprocessing service. 

In general, both options are founded in ArcObjects, but use different libraries, classes, and techniques.   You can work with both via the Web ADF Common API, ArcGIS Server SOAP API, or ArcGIS Server ArcObjects API.   The Web ADF Common API maintains a set of interfaces that expose some level of access to general spatial operations, such as using IQueryFunctionality to query a feature layer.  For ArcGIS Server data sources, the Common API provides the implementation of the IGeoprocessingFunctionality to expose a full range of operations available via geoprocessing services.  The ArcGIS Server SOAP API enables you to work with ArcGIS Server services using SOAP strings.   Again, some general spatial operations are supported via a map server proxy, but the geoprocessing server proxy provides comprehensive access to geoprocessing service and task capabilities.  The ArcGIS Server ArcObjects API provides the most fine-grained API for working with standard spatial operations and geoprocessing remotely via server context.

In every API, general spatial operations are designed to be synchronous.  On the other hand, geoprocessing tasks can be synchronous or asynchronous. You get to decide which capability provides what you need in a timely manner.   In general, a process that takes a few seconds or less is a good candidate for a synchronous process.  Any operation that takes longer may benefit from the asynchronous model, and thus would likely be deployed as a geoprocessing task.

Packaging multiple spatial operations in a single ArcObjects component and making it available on the GIS Server is possible.  Two techniques are available to extend the GIS Server in this way: utility COM objects or a Server Object Extensions.  Both are designed to off load the bulk of the remote ArcObjects calls from an ArcGIS Server client to the server so ArcObjects can run locally with the SOC.  This saves time, but both still operate within a synchronous process since the client must wait for the method call on the remote COM object to complete before continuing.  You can write your own COM utility or extension to work with ArcObjects asynchronously on the GIS Server - if you need to do some intensive ArcObjects work over a length of time and check on its status.   However, the ArcGIS Server geoprocessing framework already provides this capability, as long as the tools necessary to provide you with a solution are available.  
 
Known Limits

The .NET ADF does not have access to projection engine. For output features to show up on the map, we require one of the following: 1) GP service has an associated map service where the output features can be drawn 2) GP service will project output geometries to the spatial reference of the input geometries (model implementation) 3) GP service’s output projection is the same as the ADF Map control’s primary map resource’s spatial reference This is a known limitation at 9.2.