com.esri.core.tasks.ags.geoprocessing
Class Geoprocessor

java.lang.Object
  com.esri.core.tasks.ags.geoprocessing.Geoprocessor

public class Geoprocessor
extends Object

This class represents a single GP task as specified by the URL passed to the constructor.

Many of the methods on this class have both synchronous and asynchronous versions. The synchronous versions will return a value once the process has completed. The asynchronous versions will call a callback when the process has completed.

Information on the GP service hosting the task can be queried with getGPServiceInfo() or getGPServiceInfoAsync(CallbackListener). Information on the task itself can be queried with getGPTaskInfo() or getGPTaskInfoAsync(CallbackListener).

The GP task can be run synchronously with #execute(GPParameter[]) or #executeAsync(GPParameter[], CallbackListener). When running an asynchronous GP task with submit, there are a couple of options:

The first option is to call submitJobAndGetResultsAsync(List, String[], String[], GPJobResultCallbackListener) which will call back with a list of result parameters and a GPJobResource. The result parameters to be returned are set by the two String array parameters. The first lists the names of output parameters we want returned as data and the second lists the names of output parameters we want returned as images.

The second option is to call #submitJobAsync(GPParameter[], CallbackListener). This will call back with a GPJobResource instance that can be used with getJobStatus() or getJobStatusAsync(CallbackListener) to get the current status of the job. Once the job is determined to be complete, getResult(GPJobResource, String, boolean) or getResultAsync(GPJobResource, String, boolean, CallbackListener) can be used to get back the named output parameter.

Constructor Summary

Geoprocessor(String url)
Instantiates a new geoprocessor instance with the given task url.

Geoprocessor(String url, UserCredentials credentials)
Instantiates a new geoprocessor instance with the given task url and user credentials.

Method Summary

void	cancelJob() Cancel the current submitted job.
GPParameter[]	execute(List<GPParameter> parameters) Synchronously execute a GP task.
void	executeAsync(List<GPParameter> parameters, CallbackListener<GPParameter[]> callback) Asynchronously execute a GP task.
UserCredentials	getCredentials() Gets the credentials.
GPServiceInfo	getGPServiceInfo() Synchronously get the GP service info for the service this GP task belongs to.
void	getGPServiceInfoAsync(CallbackListener<GPServiceInfo> callback) Asynchronously get the GP service info for the service this GP task belongs to.
GPTaskInfo	getGPTaskInfo() Synchronously get the GP task info for this GP task.
void	getGPTaskInfoAsync(CallbackListener<GPTaskInfo> callback) Asynchronously get the GP task info for this GP task.
GPJobResource	getJobStatus() Synchronously gets the status of the current submitted task.
void	getJobStatusAsync(CallbackListener<GPJobResource> callback) Asynchronously gets the status of the current submitted task.
SpatialReference	getOutSR() Returns the output spatial reference set for this geoprocessing task.
SpatialReference	getProcessSR() Returns the process spatial reference set for this geoprocessing task.
GPParameter	getResult(GPJobResource jobResource, String parameterName, boolean getAsImageResult) Synchronously gets the named output parameter.
void	getResultAsync(GPJobResource jobResource, String parameterName, boolean getAsImageResult, CallbackListener<GPParameter> callback) Asynchronously gets the named output parameter.
GPJobStatusCallback	getStatusCallback() Gets the status callback.
long	getStatusCallbackInterval() Gets the status callback interval.
String	getUrl() Gets the url.
boolean	isReturnM() If returned geometry should include M values.
boolean	isReturnZ() If returned geometry should include Z values.
boolean	isRunning() Indicates whether or not this instance is running an asynchronous GP task.
void	setCredentials(UserCredentials credentials) Sets the credentials required to access a secure service.
void	setOutSR(SpatialReference outSR) Sets the well-known ID of the spatial reference of the output geometries.
void	setProcessSR(SpatialReference processSR) The well-known ID of the spatial reference that the model will use to perform geometry operations.
void	setReturnM(boolean returnM) Sets if returned geometry should contain M values.
void	setReturnZ(boolean returnZ) Sets if returned geometry should contain Z values.
protected void	setRunning(boolean running) Sets whether or not we are running submitJobAndGetResultsAsync.
void	setStatusCallback(GPJobStatusCallback statusCallback) Sets the status callback.
void	setStatusCallbackInterval(long statusCallbackInterval) Sets the status callback interval.
protected void	setUrl(String url) Sets the url.
void	submitJobAndGetResultsAsync(List<GPParameter> parameters, String[] outputDataParamNames, String[] outputImageParamNames, GPJobResultCallbackListener callback) Asynchronously submit a GP task and notify the caller via a callback when the results are available.
void	submitJobAsync(List<GPParameter> parameters, CallbackListener<GPJobResource> callback) Asynchronously submit a GP task.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Geoprocessor

public Geoprocessor(String url)

Instantiates a new geoprocessor instance with the given task url.

Parameters:

url - the url of a GP task of the form http://[gpservice-url]/[taskName]

Geoprocessor

public Geoprocessor(String url,
                    UserCredentials credentials)

Instantiates a new geoprocessor instance with the given task url and user credentials.

Parameters:

url - the url of a GP task of the form http://[gpservice-url]/[taskName]

credentials - the user credentials required to access a secure GP service

Method Detail

setUrl

protected void setUrl(String url)

Sets the url.

Parameters:

url - the new url

getUrl

public String getUrl()

Gets the url.

Returns:

the url

setCredentials

public void setCredentials(UserCredentials credentials)

Sets the credentials required to access a secure service.

Parameters:

credentials - the new credentials

getCredentials

public UserCredentials getCredentials()

Gets the credentials.

Returns:

the credentials

setStatusCallback

public void setStatusCallback(GPJobStatusCallback statusCallback)

Sets the status callback. This will be called each time the running GP task is polled during a call to

Parameters:

statusCallback - the new status callback #submitJobAndGetResultsAsync(GPParameter[], String[], String[], CallbackListener) .

getStatusCallback

public GPJobStatusCallback getStatusCallback()

Gets the status callback.

Returns:

the status callback

getOutSR

public SpatialReference getOutSR()

Returns the output spatial reference set for this geoprocessing task.

Returns:

The well-known ID of the spatial reference of the output geometries

setOutSR

public void setOutSR(SpatialReference outSR)

Sets the well-known ID of the spatial reference of the output geometries. If the output spatial reference is not specified, the output geometries are in the spatial reference of the input geometries. If the process spatial reference is specified and the output spatial reference is not specified, the output geometries are in the spatial reference of the process spatial reference.

Parameters:

outSR - The well-known ID of the spatial reference of the output geometries to set.

setReturnZ

public void setReturnZ(boolean returnZ)

Sets if returned geometry should contain Z values.

Parameters:

returnZ - true if Z values are to be returned.

isReturnZ

public boolean isReturnZ()

If returned geometry should include Z values.

Returns:

true, if Z is to be returned.

setReturnM

public void setReturnM(boolean returnM)

Sets if returned geometry should contain M values.

Parameters:

returnM - true if M values are to be returned.

isReturnM

public boolean isReturnM()

If returned geometry should include M values.

Returns:

true, if M is to be returned.

getStatusCallbackInterval

public long getStatusCallbackInterval()

Gets the status callback interval.

Returns:

the status callback interval

setStatusCallbackInterval

public void setStatusCallbackInterval(long statusCallbackInterval)

Sets the status callback interval.

Parameters:

statusCallbackInterval - the new status callback interval

getProcessSR

public SpatialReference getProcessSR()

Returns the process spatial reference set for this geoprocessing task.

Returns:

The well-known ID of the spatial reference that the model will use to perform geometry operations

setProcessSR

public void setProcessSR(SpatialReference processSR)

The well-known ID of the spatial reference that the model will use to perform geometry operations. If the process spatial reference is specified and the output spatial reference is not specified, the output geometries are in the spatial reference of the process spatial reference.

Parameters:

processSR - The well-known ID of the spatial reference that the model will use to perform geometry operations to set

isRunning

public boolean isRunning()

Indicates whether or not this instance is running an asynchronous GP task. It will be set to true when

Returns:

true, if is running #submitJobAndGetResultsAsync(GPParameter[], String[], String[], CallbackListener) starts. It will then be set to false once the task's result is ready.

setRunning

protected void setRunning(boolean running)

Sets whether or not we are running submitJobAndGetResultsAsync.

Parameters:

running - true if we are running, false otherwise

execute

public GPParameter[] execute(List<GPParameter> parameters)
                      throws Exception

Synchronously execute a GP task. This method will block until the task completes. It will then return all the output parameters if the task succeeded and null otherwise.

Parameters:

parameters - the parameters required by the task

Returns:

an array containing all the output parameters, or null

Throws:

Exception - the exception

executeAsync

public void executeAsync(List<GPParameter> parameters,
                         CallbackListener<GPParameter[]> callback)

Asynchronously execute a GP task. This method will return immediately. Once the task has completed, the given callback will be called with all of the output parameters.

Parameters:

parameters - the parameters required by the task

callback - the callback that will be called when the GP task completes

submitJobAsync

public void submitJobAsync(List<GPParameter> parameters,
                           CallbackListener<GPJobResource> callback)

Asynchronously submit a GP task. This method returns immediately. Once the GP task has been submitted, the given callback will be passed a GPJobResource instance indicating the current status of the submitted task. If you wish to get the current status of the submitted task before it completes, call either getJobStatus() or getJobStatusAsync(CallbackListener) Once it is determined that the task has completed, the results can be read with getResult(GPJobResource, String, boolean).

Parameters:

parameters - the parameters required by the task

callback - the callback that will be called once the GP task is successfully submitted getResultAsync(GPJobResource, String, boolean, CallbackListener).

submitJobAndGetResultsAsync

public void submitJobAndGetResultsAsync(List<GPParameter> parameters,
                                        String[] outputDataParamNames,
                                        String[] outputImageParamNames,
                                        GPJobResultCallbackListener callback)

Asynchronously submit a GP task and notify the caller via a callback when the results are available. This method will return immediately. The submitted task will be polled internally and once the task is complete, the requested results will be queried and returned to the caller via the given callback.

If you wish to be notified of the task's status each time it is polled, use

Parameters:

parameters - the parameters required by the task

outputDataParamNames - a list of names of output parameters we want returned as data

outputImageParamNames - a list of names of output parameters we want returned as images

callback - the callback that will be called once the requested results are available setStatusCallback(GPJobStatusCallback) to set a callback to be called each time the task is polled.

To set which output parameters you want returned, use the outputDataParamNames parameter to list the names of output parameters you want as data and outputImageParamNames to list the names of those you want as images. Note that a parameter name can go in both lists if you want it returned as both data and an image. The returned output parameters will be ordered as all of the data results followed by all of the image results.

getJobStatus

public GPJobResource getJobStatus()
                           throws Exception

Synchronously gets the status of the current submitted task. If the returned GPJobResource indicates that the task has completed successfully, it can be used with getResult(GPJobResource, String, boolean).

Returns:

the job status

Throws:

Exception - the exception getResultAsync(GPJobResource, String, boolean, CallbackListener) to get a named output parameter.

getJobStatusAsync

public void getJobStatusAsync(CallbackListener<GPJobResource> callback)

Asynchronously gets the status of the current submitted task. The given callback will be called when the status is available. If the returned GPJobResource indicates that the task has completed successfully, it can be used with getResult(GPJobResource, String, boolean).

Parameters:

callback - the callback that will be called when the current status is available

cancelJob

public void cancelJob()

Cancel the current submitted job.

getResult

public GPParameter getResult(GPJobResource jobResource,
                             String parameterName,
                             boolean getAsImageResult)
                      throws Exception

Synchronously gets the named output parameter. As this method takes a GPJobResource parameter, it can be used to request the outputs of any successful run of the GP task represented by this Geoprocessor instance. This method can be used to return the output parameter as either data or an image by setting the getAsImageResult parameter.

Parameters:

jobResource - a job resource returned by a successfully completed GP task

parameterName - the parameter name

getAsImageResult - set true to return the output parameter as an image and false to return it as data

Returns:

the output parameter

Throws:

Exception - the exception

getResultAsync

public void getResultAsync(GPJobResource jobResource,
                           String parameterName,
                           boolean getAsImageResult,
                           CallbackListener<GPParameter> callback)

Asynchronously gets the named output parameter. As this method takes a GPJobResource parameter, it can be used to request the outputs of any successful run of the GP task represented by this Geoprocessor instance. When the output parameter is ready it will be passed to the given callback. The output parameter will be returned as data if the getAsImageResult parameter is false and as an image if getAsImageResult is true.

Parameters:

jobResource - a job resource returned by a successfully completed GP task

parameterName - the parameter name

getAsImageResult - set true to return the output parameter as an image and false to return it as data

callback - the callback

getGPServiceInfo

public GPServiceInfo getGPServiceInfo()
                               throws Exception

Synchronously get the GP service info for the service this GP task belongs to.

Returns:

the GP service info

Throws:

Exception - the exception

See Also:

GPServiceInfo

getGPServiceInfoAsync

public void getGPServiceInfoAsync(CallbackListener<GPServiceInfo> callback)

Asynchronously get the GP service info for the service this GP task belongs to. The given callback will be passed the service info when it is available.

Parameters:

callback - the callback

See Also:

GPServiceInfo

getGPTaskInfo

public GPTaskInfo getGPTaskInfo()
                         throws Exception

Synchronously get the GP task info for this GP task.

Returns:

the GP task info

Throws:

Exception - the exception

See Also:

GPTaskInfo

getGPTaskInfoAsync

public void getGPTaskInfoAsync(CallbackListener<GPTaskInfo> callback)

Asynchronously get the GP task info for this GP task. The given callback will be passed the task info when it is available.

Parameters:

callback - the callback

See Also:

GPTaskInfo