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 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 andstart()
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 usingaddJobChangedListener(Runnable)
, then callinggetMessages()
to retrieve an up to date list of messages. Progress updates can be monitored with a progress listener set usingaddProgressChangedListener(Runnable)
, then callinggetProgress()
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 usinggetResult()
. If an error occurs, the status will change to FAILED andgetError()
will provide the error. All status changes are monitored with a job changed listener set usingaddJobChangedListener(Runnable)
.Jobs can be paused using
pause()
and restarted usingstart()
. 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
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addJobChangedListener(Runnable listener)
Deprecated.100.14.0.void
addJobDoneListener(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(Runnable listener)
Adds a listener to run each time the progress of this job changes.void
addStatusChangedListener(Runnable listener)
Adds a listener to be called when an update is received from the Job.boolean
cancel()
Deprecated.100.14.0.ListenableFuture<Boolean>
cancelAsync()
Cancels this Job and waits for any asynchronous, server-side operations to be canceled.static Job
fromJson(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.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 Object
getResult()
Gets the result of this job.String
getServerJobId()
Gets the ID used by the server to identify this job.Job.Status
getStatus()
Gets the current status of this job.Map<String,Object>
getUnknownJson()
Jobs never have any unknown JSON so this returns an empty Map.Map<String,Object>
getUnsupportedJson()
Jobs never have any unsupported JSON so this returns an empty Map.String
getUri()
Gets the URI of this job.boolean
pause()
Pauses this job.boolean
removeJobChangedListener(Runnable listener)
Deprecated.since 100.15.0.boolean
removeJobDoneListener(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 usingaddJobMessageAddedListener(JobMessageAddedListener)
.boolean
removeProgressChangedListener(Runnable listener)
Removes a progress changed listener so that it will not be called when the job progress changes.boolean
removeStatusChangedListener(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(String uri)
Deprecated.As of 100.1.0, no replacement.boolean
start()
Starts or resumes this job.String
toJson()
Serializes this object to a JSON string.
-
-
-
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 interfaceRemoteResource
- 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 interfaceRemoteResource
- 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 interfaceRemoteResource
- 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 interfaceRemoteResource
- Returns:
- the RequestConfiguration object, or null if none has been set
- Since:
- 100.0.0
- See Also:
RequestConfiguration
-
setUri
@Deprecated public void setUri(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 String getUri()
Gets the URI of this job.- Specified by:
getUri
in interfaceRemoteResource
- Returns:
- the URI of this job
- Since:
- 100.0.0
-
fromJson
public static Job fromJson(String json)
Creates a Job instance from a JSON string.- Parameters:
json
- a JSON string that represents a Job- Returns:
- a Job instance
- Throws:
IllegalArgumentException
- if json is null or empty- Since:
- 100.0.0
-
toJson
public 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 interfaceJsonSerializable
- Returns:
- a JSON string
-
getUnknownJson
public Map<String,Object> getUnknownJson()
Jobs never have any unknown JSON so this returns an empty Map.- Specified by:
getUnknownJson
in interfaceJsonSerializable
- Returns:
- an empty unmodifiable Map
- Since:
- 100.0.0
-
getUnsupportedJson
public Map<String,Object> getUnsupportedJson()
Jobs never have any unsupported JSON so this returns an empty Map.- Specified by:
getUnsupportedJson
in interfaceJsonSerializable
- 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()
isJob.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 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 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 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. UsecancelAsync()
instead to allow asynchronous server-side cancellation to complete.Cancel the job.The job is canceled and goes into a failure status
In addition, theJob.Status.FAILED
. For jobs running on a server, a cancel request will be sent for the associatedgetServerJobId()
. 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:GenerateOfflineMapJob
is composed of several server-side jobs, depending on the types of layers in yourArcGISMap
. 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<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
In addition, theJob.Status.FAILED
status once all cancellation tasks have completed. For jobs running on a server, a cancel request is sent for the associatedgetServerJobId()
. 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:GenerateOfflineMapJob
is composed of several server-side jobs, depending on the layers in yourArcGISMap
. 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 toJob.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(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:
IllegalArgumentException
- if listener is null- Since:
- 100.0.0
-
removeJobDoneListener
public boolean removeJobDoneListener(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(Runnable listener)
Deprecated.100.14.0. UseaddStatusChangedListener(Runnable)
andaddJobMessageAddedListener(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:
IllegalArgumentException
- if listener is null- Since:
- 100.0.0
-
removeJobChangedListener
@Deprecated public boolean removeJobChangedListener(Runnable listener)
Deprecated.since 100.15.0. UseremoveStatusChangedListener(Runnable)
andremoveJobMessageAddedListener(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(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:
IllegalArgumentException
- if listener is null- Since:
- 100.1.0
- See Also:
getProgress()
-
removeProgressChangedListener
public boolean removeProgressChangedListener(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(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:
IllegalArgumentException
- if listener is null- Since:
- 100.14.0
- See Also:
getStatus()
-
removeStatusChangedListener
public boolean removeStatusChangedListener(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:
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 usingaddJobMessageAddedListener(JobMessageAddedListener)
.- Parameters:
listener
- the listener to unregister- Returns:
- true if the listener was successfully removed; false otherwise
- Since:
- 100.14.0
-
-