Module com.esri.arcgisruntime
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, UtilityNetworkValidationJob
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 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 status changed listener set using addStatusChangedListener(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 status changed listener set using addStatusChangedListener(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

  • Field Details

  • Method Details

    • 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:

    • getUri

      public 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(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 interface JsonSerializable
      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 interface JsonSerializable
      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 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 List<Job.Message> getMessages()
      Gets a list containing a snapshot of messages describing the state of this job when this method is called.

      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:

    • 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:

    • 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:

    • 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

    • 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 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:

      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(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

    • 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:

    • 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:

    • 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

      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