HERE Android SDK Developer's Guide

CLE2Task<ResultType>

The class CLE2Task<ResultType> is a member of com.here.android.mpa.customlocation2 .

Type Parameters:

  • ResultType

    type of data the task retrieves from the service

Class Summary

public class CLE2Task

extends java.lang.Object

Encapsulates an asynchronous CLE2 task (that usually involves network communication and/or database operations) and provides some common operations like observing, waiting for the result, cancelling or getting the result.

[For complete information, see the section Class Details]

Nested Class Summary

Table 1. Nested Classes in CLE2Task<ResultType>
Nested Classes

public static abstract interface CLE2Task.Callback

Used to notify the client of the result of the operation.

Method Summary

Table 2. Methods in CLE2Task<ResultType>
Methods

public CLE2Task<ResultType> cancel ()

Attempts to cancel this task if it is running.

public CLE2Error getError ()

Gets the status of a finished task.

public ResultType getResult ()

Gets result of the operation represented by this task.

public boolean isFinished ()

Checks if the task has finished.

public boolean isStarted ()

Checks if the task has been started.

public CLE2Task<ResultType> start ()

Starts this task.

public CLE2Task<ResultType> start (Callback<ResultType> callback)

Starts this task and subscribes the supplied callback for result.

public CLE2Task<ResultType> subscribe (Callback<ResultType> callback)

Add a listener to be notified when this task finishes.

public CLE2Task<ResultType> unsubscribe (Callback<ResultType> callback)

Removes a listener from the list of subscribers to this task.

public CLE2Task<ResultType> waitForResult (long timeout, TimeUnit unit)

Waits for task's completion or until specified time passes.

public CLE2Task<ResultType> waitForResult ()

Waits for task's completion.

Class Details

Encapsulates an asynchronous CLE2 task (that usually involves network communication and/or database operations) and provides some common operations like observing, waiting for the result, cancelling or getting the result.

A typical use for a CLE2Task involves creating a task, subscribing to it and starting its execution. The factory methods usually looks something like newActionTask(parameters) where Action is a descriptive name of what the task will do. For example, if you don't care about holding onto the task for later use or having more than one subscriber, you might write CLE2DataManager.getInstance().newListLayersTask(StorageType.LOCAL).start(myListener) to create and start a task that will get the list of locally stored layers.

CLE2Task also provides some more advanced features. For example, if you are performing a background operation that involves interacting with CLE2, a CLE2Task can be used in a synchronous manner by means of calling waitForResult() method and then getting the result and error from the the finished task.

Having multiple subscribers to the task is also possible.

And finally, since CLE2Task object represents a unit of work, it can be held onto for later use, passed around, run repeatedly multiple times (for example, retrying a failed operation) and canceled.

Method Details

public CLE2Task<ResultType> cancel ()

Attempts to cancel this task if it is running. There is no guarantee that the task will get cancelled, it might happen that it might be too late in the process to abort. Regardless of the outcome, all subscribers will get called. Refer to the error status in the subscriber callback ( onTaskFinished(ResultType, CLE2Request.CLE2Error)) to determine if the task was actually cancelled or not.

Returns:

this task, for method chaining

public CLE2Error getError ()

Gets the status of a finished task. This is how to check if the operation finished successfully or learn of the reason for failure.

Only tasks that finished and are not currently in progress give a guarantee of returning a meaningful value.

Returns:

error status

public ResultType getResult ()

Gets result of the operation represented by this task. Only tasks that finished successfully and are not currently in progress give a guarantee of returning a meaningful value.

Returns:

result of the task if finished, undefined otherwise (refer to the documentation of the task creator)

public boolean isFinished ()

Checks if the task has finished.

NOTE: a task that is not started is always not finished.

Returns:

true if this task finished, false otherwise

public boolean isStarted ()

Checks if the task has been started.

NOTE: a finished task is also started. A task that is running is one that is started but not finished.

Returns:

true if this task was already started, false otherwise

public CLE2Task<ResultType> start ()

Starts this task. It will be run asynchronously. Attempting to start a task that is already running has no effect. Starting the task that has already finished will make it run again.

To be notified about the task's result you need to subscribe to it using subscribe(CLE2Task.Callback) or if synchronous operation is required waitForResult() and use getResult() and getError().

Returns:

this task, for method chaining

public CLE2Task<ResultType> start (Callback<ResultType> callback)

Starts this task and subscribes the supplied callback for result. All subscribers are called on the main thread when the task finishes. Attempting to start a task that is already running is equivalent to calling subscribe(CLE2Task.Callback) on it with the callback . Starting the task that has already finished will make it run again.

Parameters:

  • callback

    a subscriber to be notified of the result of this task

Returns:

this task, for method chaining

public CLE2Task<ResultType> subscribe (Callback<ResultType> callback)

Add a listener to be notified when this task finishes. They will be called in the same order as they were added.

Subscribing on a task that already finished will result in callback being invoked immediately with the result.

All subscribers are called on the main thread.

Parameters:

  • callback

Returns:

this task, for method chaining

public CLE2Task<ResultType> unsubscribe (Callback<ResultType> callback)

Removes a listener from the list of subscribers to this task. This method has no effect if the callback is not already a subscriber.

Parameters:

  • callback

    a callback/listener to subscribe on this task

Returns:

this task, for method chaining

public CLE2Task<ResultType> waitForResult (long timeout, TimeUnit unit)

Waits for task's completion or until specified time passes. Returns immediately if the task has already finished or is not started.

Important: never call this method from the main thread, that will result in RuntimeException . It is meant to be used in situations where you run a non-trivial sequence of operations on your own background thread.

Parameters:

  • timeout

    the maximum time to wait

  • unit

    the time unit of the timeout argument

Returns:

this task, for method chaining

public CLE2Task<ResultType> waitForResult ()

Waits for task's completion. Returns immediately if the task has already finished or is not started.

Important: never call this method from the main thread, that will result in RuntimeException . It is meant to be used in situations where you run a non-trivial sequence of operations on your own background thread.

Returns:

this task, for method chaining