Package com.esri.arcgisruntime.concurrent

Class Job

java.lang.Object

com.esri.arcgisruntime.concurrent.Job

All Implemented Interfaces:

JsonSerializable, RemoteResource

Direct Known Subclasses:

DownloadPreplannedOfflineMapJob, EstimateTileCacheSizeJob, ExportTileCacheJob, ExportVectorTilesJob, GenerateGeodatabaseJob, GenerateOfflineMapJob, GeoprocessingJob, OfflineMapSyncJob, SyncGeodatabaseJob

public abstract class Job
extends java.lang.Object
implements RemoteResource, JsonSerializable

Represents the base class of a long running operation that is performed by an ArcGIS Server asynchronous service operation. A Job has regular status and progress updates as it is executed and a result is returned when it is done.

Job instances are created by tasks and returned by task methods that initiate long running operations. Jobs are returned in a Job.Status.NOT_STARTED state and start() must be called to start the associated operation, the job will then have a status of STARTED.

When the server accepts the job, it assigns a unique ID to the job which is available with getServerJobId(). The job then periodically polls to receive progress of the job on the server and messages may be returned. Status updates can be monitored with a job changed listener set using addJobChangedListener(Runnable), then calling getMessages() to retrieve an up to date list of messages. Progress updates can be monitored with a progress listener set using addProgressChangedListener(Runnable), then calling getProgress() to get the percentage of the job that has been completed.

If the job completes successfully, the status will change to SUCCEEDED and the result of the job is retrieved from the server, the JobDone event will fire, add a listener for this using the addJobDoneListener(Runnable). The result can be accessed using getResult(). If an error occurs, the status will change to FAILED and getError() will provide the error. All status changes are monitored with a job changed listener set using addJobChangedListener(Runnable).

Jobs can be paused using pause() and restarted using start(). Paused jobs stop polling for status updates but are not always on the server (this is job type dependant). If a job is paused and then started after the server's default job cleanup schedule, it will be given a new unique ID by the server and will start from the beginning.

Since:

100.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Job.Message	Represents a message indicating progress of a Job.
static class	Job.MessageSeverity	The different levels of severity of a job message.
static class	Job.MessageSource	The origin of a job message.
static class	Job.Status	Signifies the status of a Job.

Field Summary

Fields

Modifier and Type	Field	Description
protected Credential	mCredential
protected RequestConfiguration	mRequestConfiguration

Method Summary

Modifier and Type	Method	Description
void	addJobChangedListener(java.lang.Runnable listener)	Deprecated. 100.14.0.
void	addJobDoneListener(java.lang.Runnable listener)	Adds a listener to run on successful or unsuccessful completion of the job.
void	addJobMessageAddedListener(JobMessageAddedListener listener)	Registers the given JobMessageAddedListener to be called when an update is received from the Job.
void	addProgressChangedListener(java.lang.Runnable listener)	Adds a listener to run each time the progress of this job changes.
void	addStatusChangedListener(java.lang.Runnable listener)	Adds a listener to be called when an update is received from the Job.
boolean	cancel()	Deprecated. 100.14.0.
ListenableFuture<java.lang.Boolean>	cancelAsync()	Cancels this Job and waits for any asynchronous, server-side operations to be canceled.
static Job	fromJson(java.lang.String json)	Creates a Job instance from a JSON string.
Credential	getCredential()	Gets the credential used to authenticate the user with this job.
ArcGISRuntimeException	getError()	Gets the error if this job has terminated due to an error.
java.util.List<Job.Message>	getMessages()	Gets a list containing a snapshot of messages describing the state of this job when this method is called.
int	getProgress()	Gets a measure of the progress of this job.
RequestConfiguration	getRequestConfiguration()	Gets the RequestConfiguration object in use by this job.
abstract java.lang.Object	getResult()	Gets the result of this job.
java.lang.String	getServerJobId()	Gets the ID used by the server to identify this job.
Job.Status	getStatus()	Gets the current status of this job.
java.util.Map<java.lang.String,java.lang.Object>	getUnknownJson()	Jobs never have any unknown JSON so this returns an empty Map.
java.util.Map<java.lang.String,java.lang.Object>	getUnsupportedJson()	Jobs never have any unsupported JSON so this returns an empty Map.
java.lang.String	getUri()	Gets the URI of this job.
boolean	pause()	Pauses this job.
boolean	removeJobChangedListener(java.lang.Runnable listener)	Deprecated. since 100.15.0.
boolean	removeJobDoneListener(java.lang.Runnable listener)	Removes a job done listener so that it will not be called when the job completes.
boolean	removeJobMessageAddedListener(JobMessageAddedListener listener)	Unregisters the given JobMessageAddedListener that was previously added using addJobMessageAddedListener(JobMessageAddedListener).
boolean	removeProgressChangedListener(java.lang.Runnable listener)	Removes a progress changed listener so that it will not be called when the job progress changes.
boolean	removeStatusChangedListener(java.lang.Runnable listener)	Removes a status changed listener so that it will not be called when the job status changes.
void	setCredential(Credential credential)	Sets the credential used to authenticate the user with this job.
void	setRequestConfiguration(RequestConfiguration requestConfiguration)	Sets configuration parameters used for network requests sent using this job.
void	setUri(java.lang.String uri)	Deprecated. As of 100.1.0, no replacement.
boolean	start()	Starts or resumes this job.
java.lang.String	toJson()	Serializes this object to a JSON string.

Methods inherited from class java.lang.Object

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

Field Detail

mCredential

protected Credential mCredential

mRequestConfiguration

protected RequestConfiguration mRequestConfiguration

Method Detail

setCredential

public void setCredential(Credential credential)

Sets the credential used to authenticate the user with this job.

Specified by:

setCredential in interface RemoteResource

Parameters:

credential - the credential used to authenticate the user with this job

Since:

100.0.0

getCredential

public Credential getCredential()

Gets the credential used to authenticate the user with this job.

Specified by:

getCredential in interface RemoteResource

Returns:

the credential, or null if there is none

Since:

100.0.0

setRequestConfiguration

public void setRequestConfiguration(RequestConfiguration requestConfiguration)

Sets configuration parameters used for network requests sent using this job. The global RequestConfiguration is used if no RequestConfiguration is set.

Specified by:

setRequestConfiguration in interface RemoteResource

Parameters:

requestConfiguration - object containing the parameters to use

Since:

100.0.0

getRequestConfiguration

public RequestConfiguration getRequestConfiguration()

Gets the RequestConfiguration object in use by this job.

Specified by:

getRequestConfiguration in interface RemoteResource

Returns:

the RequestConfiguration object, or null if none has been set

Since:

100.0.0

See Also:

RequestConfiguration

setUri

@Deprecated
public void setUri(java.lang.String uri)

Deprecated.

As of 100.1.0, no replacement.

Sets the URI of this job.

Parameters:

uri - the URI of this job

Since:

100.0.0

getUri

public java.lang.String getUri()

Gets the URI of this job.

Specified by:

getUri in interface RemoteResource

Returns:

the URI of this job

Since:

100.0.0

fromJson

public static Job fromJson(java.lang.String json)

Creates a Job instance from a JSON string.

Parameters:

json - a JSON string that represents a Job

Returns:

a Job instance

Throws:

java.lang.IllegalArgumentException - if json is null or empty

Since:

100.0.0

toJson

public java.lang.String toJson()

Description copied from interface: JsonSerializable

Serializes this object to a JSON string. Note that unknown JSON is omitted from the serialized string.

Specified by:

toJson in interface JsonSerializable

Returns:

a JSON string

getUnknownJson

public java.util.Map<java.lang.String,java.lang.Object> getUnknownJson()

Jobs never have any unknown JSON so this returns an empty Map.

Specified by:

getUnknownJson in interface JsonSerializable

Returns:

an empty unmodifiable Map

Since:

100.0.0

getUnsupportedJson

public java.util.Map<java.lang.String,java.lang.Object> getUnsupportedJson()

Jobs never have any unsupported JSON so this returns an empty Map.

Specified by:

getUnsupportedJson in interface JsonSerializable

Returns:

an empty unmodifiable Map

Since:

100.0.0

getError

public ArcGISRuntimeException getError()

Gets the error if this job has terminated due to an error.

The error is available when the getStatus() is Job.Status.FAILED.

Returns:

an ArcGISRuntimeException describing the error, or null if the job succeeded or is not done yet

Since:

100.0.0

getMessages

public java.util.List<Job.Message> getMessages()

Gets a list containing a snapshot of messages describing the state of this job when this method is called. For an up to date list of messages, call this method once each time a JobChanged or JobDone event fires.

When a new message is added, the JobMessageAddedEvent is fired.

Returns:

an unmodifiable List of messages describing the current state of this job

Since:

100.0.0

See Also:

addJobMessageAddedListener(JobMessageAddedListener)

getProgress

public int getProgress()

Gets a measure of the progress of this job. This is the percentage of the job that has been completed, ranging from zero before starting to 100 when complete.

When the progress value changes, the progress changed listener — a Runnable — will be invoked, assuming you have added such a listener to the job.

Returns:

the percentage of the job that has been completed

Since:

100.1.0

See Also:

addProgressChangedListener(Runnable)

getResult

public abstract java.lang.Object getResult()

Gets the result of this job.

Returns:

an Object containing the result, or null if the job failed or is not done yet

Since:

100.0.0

getStatus

public Job.Status getStatus()

Gets the current status of this job.

When status changes, the status changed listener — a Runnable — will be invoked, assuming you have added such a listener to the job.

Returns:

the status of this job

Since:

100.0.0

See Also:

addStatusChangedListener(Runnable)

getServerJobId

public java.lang.String getServerJobId()

Gets the ID used by the server to identify this job.

Returns:

the server ID of this job

Since:

100.0.0

cancel

@Deprecated
public boolean cancel()

Deprecated.

100.14.0. Use cancelAsync() instead to allow asynchronous server-side cancellation to complete.

Cancel the job.

The job is canceled and goes into a failure status Job.Status.FAILED. For jobs running on a server, a cancel request will be sent for the associated getServerJobId(). You should always cancel unneeded jobs (for example, when exiting your app) to avoid placing unnecessary load on the server. For example, server-side jobs include:

• ExportTileCacheJob
• ExportVectorTilesJob
• GenerateGeodatabaseJob
• GeoprocessingJob

In addition, the GenerateOfflineMapJob is composed of several server-side jobs, depending on the types of layers in your ArcGISMap. Canceling this high-level job will also send a cancel request to the underlying server jobs.

Returns:

true if the job was canceled, false if the job is already succeeded or failed. Returns false if an error occurs.

Since:

100.0.0

cancelAsync

public ListenableFuture<java.lang.Boolean> cancelAsync()

Cancels this Job and waits for any asynchronous, server-side operations to be canceled.

The job is canceled and will result in a Job.Status.FAILED status once all cancellation tasks have completed. For jobs running on a server, a cancel request is sent for the associated getServerJobId(). You should always cancel unneeded jobs (for example, when exiting your app) to avoid placing unnecessary load on the server. Examples of server-side jobs include:

• ExportTileCacheJob
• ExportVectorTilesJob
• GenerateGeodatabaseJob
• GeoprocessingJob

In addition, the GenerateOfflineMapJob is composed of several server-side jobs, depending on the layers in your ArcGISMap. Canceling this high-level job will also send a cancel request to the underlying server jobs.

Upon calling this method, the getStatus() is immediately set to Job.Status.CANCELING.

Returns:

true if the job was canceled, false if the job is already succeeded or failed. Returns false if an error occurs.

Since:

100.14.0

pause

public boolean pause()

Pauses this job.

Returns:

true if the job was successfully paused; false if it is already paused or already done or an error occurred

Since:

100.0.0

start

public boolean start()

Starts or resumes this job. Call this method to start the job initially and also to resume it after it is paused.

Returns:

true if the job was successfully started/resumed; false if it has not been paused or is already done, or if an error occurs

Since:

100.0.0

addJobDoneListener

public void addJobDoneListener(java.lang.Runnable listener)

Adds a listener to run on successful or unsuccessful completion of the job. The listener will run immediately if the job is already complete when this method is called.

Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

Parameters:

listener - a Runnable to run when the job is done

Throws:

java.lang.IllegalArgumentException - if listener is null

Since:

100.0.0

removeJobDoneListener

public boolean removeJobDoneListener(java.lang.Runnable listener)

Removes a job done listener so that it will not be called when the job completes.

Parameters:

listener - the listener to be removed

Returns:

true if the listener was removed, otherwise false

Since:

100.0.0

addJobChangedListener

@Deprecated
public void addJobChangedListener(java.lang.Runnable listener)

Deprecated.

100.14.0. Use addStatusChangedListener(Runnable) and addJobMessageAddedListener(JobMessageAddedListener) instead.

Adds a listener to run each time the status of this job changes or a new JobMessage is generated.

Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

Parameters:

listener - a Runnable to run when the job changes

Throws:

java.lang.IllegalArgumentException - if listener is null

Since:

100.0.0

removeJobChangedListener

@Deprecated
public boolean removeJobChangedListener(java.lang.Runnable listener)

Deprecated.

since 100.15.0. Use removeStatusChangedListener(Runnable) and removeJobMessageAddedListener(JobMessageAddedListener) instead.

Removes a job changed listener so that it will not be called when the job changes.

Parameters:

listener - the listener to be removed

Returns:

true if the listener was removed, otherwise false

Since:

100.0.0

addProgressChangedListener

public void addProgressChangedListener(java.lang.Runnable listener)

Adds a listener to run each time the progress of this job changes. This method will be called each time the job's progress increments.

Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

Parameters:

listener - a Runnable to run when the job progress changes

Throws:

java.lang.IllegalArgumentException - if listener is null

Since:

100.1.0

See Also:

getProgress()

removeProgressChangedListener

public boolean removeProgressChangedListener(java.lang.Runnable listener)

Removes a progress changed listener so that it will not be called when the job progress changes.

Parameters:

listener - the listener to be removed

Returns:

true if the listener was removed, otherwise false

Since:

100.1.0

addStatusChangedListener

public void addStatusChangedListener(java.lang.Runnable listener)

Adds a listener to be called when an update is received from the Job.

Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

Parameters:

listener - a Runnable to run when the job progress changes

Throws:

java.lang.IllegalArgumentException - if listener is null

Since:

100.14.0

See Also:

getStatus()

removeStatusChangedListener

public boolean removeStatusChangedListener(java.lang.Runnable listener)

Removes a status changed listener so that it will not be called when the job status changes.

Parameters:

listener - the listener to be removed

Returns:

true if the listener was removed, otherwise false

Since:

100.14.0

addJobMessageAddedListener

public void addJobMessageAddedListener(JobMessageAddedListener listener)

Registers the given JobMessageAddedListener to be called when an update is received from the Job.

Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

Parameters:

listener - the listener to register

Throws:

java.lang.IllegalArgumentException - if the JobMessageAddedListener is null

Since:

100.14.0

See Also:

removeJobMessageAddedListener(JobMessageAddedListener)

removeJobMessageAddedListener

public boolean removeJobMessageAddedListener(JobMessageAddedListener listener)

Unregisters the given JobMessageAddedListener that was previously added using addJobMessageAddedListener(JobMessageAddedListener).

Parameters:

listener - the listener to unregister

Returns:

true if the listener was successfully removed; false otherwise

Since:

100.14.0