Class OfflineMapTask
- java.lang.Object
-
- com.esri.arcgisruntime.tasks.offlinemap.OfflineMapTask
-
- All Implemented Interfaces:
RemoteResource
,Loadable
public final class OfflineMapTask extends Object implements Loadable, RemoteResource
A task used to take a map offline. Taking a map offline involves downloading an online map and its data, including all the supported layers, tables, renderers, web map configuration etc. so that it can be used offline without a network connection.There are two workflows available for taking maps offline:
- the ahead-of-time workflow (also sometimes referred to as the preplanned workflow)
- the on-demand workflow
Ahead-of-time workflow - In this workflow the author of a web map defines geographical areas (offline map areas) to take offline. ArcGIS Online, or ArcGIS Enterprise, uses these to prepare offline map content that is stored online. ArcGIS Runtime apps download the offline map content to a device using the
DownloadPreplannedOfflineMapJob
. Note that ArcGIS Runtime APIs refer to an offline map area as aPreplannedMapArea
. For more information about authoring offline map areas, see Take web maps offline.On-demand workflow - Here the app passes a specific area of interest to a
GenerateOfflineMapJob
to generate and download the map content to the device. Using this workflow, you can choose to keep online only services (e.g. those that require a network connection) in your offline map. Be aware that an offline map which uses online only services will require a network connection and may require authentication.- Since:
- 100.1.0
-
-
Constructor Summary
Constructors Constructor Description OfflineMapTask(ArcGISMap onlineMap)
Create the offline map task for the provided online map.OfflineMapTask(PortalItem portalItem)
Constructs the offline map task with the provided portal item, which must represent a web map.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addDoneLoadingListener(Runnable listener)
Adds a listener to the loadable resource that is invoked when loading has completed.void
addLoadStatusChangedListener(LoadStatusChangedListener listener)
Adds aLoadStatusChangedListener
to the loadable resource that is invoked whenever the load status changes.void
cancelLoad()
Cancels loading metadata for the object.ListenableFuture<DownloadPreplannedOfflineMapParameters>
createDefaultDownloadPreplannedOfflineMapParametersAsync(PreplannedMapArea preplannedMapArea)
Executes an asynchronous operation to create a DownloadPreplannedOfflineMapParameters from the specified PreplannedMapArea.ListenableFuture<GenerateOfflineMapParameters>
createDefaultGenerateOfflineMapParametersAsync(Geometry areaOfInterest)
Executes an asynchronous operation to create a set of default parameters that can be used to take an online map offline.ListenableFuture<GenerateOfflineMapParameters>
createDefaultGenerateOfflineMapParametersAsync(Geometry areaOfInterest, double minScale, double maxScale)
Executes an asynchronous operation to create a GenerateOfflineMapParameters from the specified area of interest, min scale, and max scale.ListenableFuture<GenerateOfflineMapParameterOverrides>
createGenerateOfflineMapParameterOverridesAsync(GenerateOfflineMapParameters parameters)
Executes an asynchronous operation to create a GenerateOfflineMapParameterOverrides object that is populated to reflect the values in the provided GenerateOfflineMapParameters.DownloadPreplannedOfflineMapJob
downloadPreplannedOfflineMap(DownloadPreplannedOfflineMapParameters parameters, String downloadDirectoryPath)
Creates aDownloadPreplannedOfflineMapJob
that can be used to download the preplanned map area specified by the given parameters object.DownloadPreplannedOfflineMapJob
downloadPreplannedOfflineMap(PreplannedMapArea area, String downloadDirectoryPath)
Deprecated.as of 100.10.0.DownloadPreplannedOfflineMapJob
downloadPreplannedOfflineMap(PreplannedMapArea area, String downloadDirectoryPath, boolean excludeBasemap)
Deprecated.As of 100.4.0, replaced bydownloadPreplannedOfflineMap(DownloadPreplannedOfflineMapParameters, String)
.GenerateOfflineMapJob
generateOfflineMap(GenerateOfflineMapParameters parameters, String downloadDirectoryPath)
Creates aGenerateOfflineMapJob
that can be used to generate an offline map from an online map, using the specified parameters.GenerateOfflineMapJob
generateOfflineMap(GenerateOfflineMapParameters parameters, String downloadDirectoryPath, GenerateOfflineMapParameterOverrides parameterOverrides)
Creates aGenerateOfflineMapJob
that can be used to generate an offline map from an online map, using the specified parameters and overrides.Credential
getCredential()
Gets the credential used to authenticate the user with this task.ArcGISRuntimeException
getLoadError()
Returns the most recent error that was encountered when the loadable resource transitioned to theLoadStatus.FAILED_TO_LOAD
state, either due to calling theLoadable.loadAsync()
orLoadable.retryLoadAsync()
method.LoadStatus
getLoadStatus()
Returns theLoadStatus
of the loadable resource.ListenableFuture<OfflineMapCapabilities>
getOfflineMapCapabilitiesAsync(GenerateOfflineMapParameters parameters)
Executes an asynchronous operation to get theOfflineMapCapabilities
containing information on which layers will be included in an offline map.ArcGISMap
getOnlineMap()
Gets the online map to be taken offline.PortalItem
getPortalItem()
Gets the portal item that specifies the map to be taken offline.ListenableFuture<List<PreplannedMapArea>>
getPreplannedMapAreasAsync()
Executes an asynchronous operation to get a list of preplanned map areas.RequestConfiguration
getRequestConfiguration()
Gets the RequestConfiguration object in use by this task.String
getUri()
Gets the URI of this task.void
loadAsync()
Loads the metadata of the loadable resource asynchronously.boolean
removeDoneLoadingListener(Runnable listener)
Removes a done loading listener from the loadable resource.boolean
removeLoadStatusChangedListener(LoadStatusChangedListener listener)
Removes aLoadStatusChangedListener
from the loadable resource.void
retryLoadAsync()
Loads or retries loading metadata for the object asynchronously.void
setCredential(Credential credential)
Sets the credential used to authenticate the user with this task.void
setRequestConfiguration(RequestConfiguration requestConfiguration)
Sets configuration parameters used for network requests sent using this task.
-
-
-
Constructor Detail
-
OfflineMapTask
public OfflineMapTask(ArcGISMap onlineMap)
Create the offline map task for the provided online map. The online map must represent a web map.The online map must be of type
PortalItem.Type.WEBMAP
, either on ArcGIS Online or an on-premise ArcGIS Enterprise Portal.- Parameters:
onlineMap
- an ArcGISMap that represents a web map- Throws:
IllegalArgumentException
- if onlineMap is nullIllegalArgumentException
- if onlineMap is not a web map- Since:
- 100.1.0
-
OfflineMapTask
public OfflineMapTask(PortalItem portalItem)
Constructs the offline map task with the provided portal item, which must represent a web map. In other words, the portal item must be of typePortalItem.Type.WEBMAP
and available either on ArcGIS Online or an on-premise ArcGIS Enterprise Portal- Parameters:
portalItem
- a portal item that represents a web map- Throws:
IllegalArgumentException
- if portalItem is null- Since:
- 100.1.0
- See Also:
PortalItem
-
-
Method Detail
-
setCredential
public void setCredential(Credential credential)
Sets the credential used to authenticate the user with this task.- Specified by:
setCredential
in interfaceRemoteResource
- Parameters:
credential
- the credential used to authenticate the user with this task- Since:
- 100.1.0
-
getCredential
public Credential getCredential()
Gets the credential used to authenticate the user with this task.- Specified by:
getCredential
in interfaceRemoteResource
- Returns:
- the credential, or null if there is none
- Since:
- 100.1.0
-
setRequestConfiguration
public void setRequestConfiguration(RequestConfiguration requestConfiguration)
Sets configuration parameters used for network requests sent using this task. The global RequestConfiguration is used if no RequestConfiguration is set.- Specified by:
setRequestConfiguration
in interfaceRemoteResource
- Parameters:
requestConfiguration
- contains the parameters to use- Since:
- 100.1.0
-
getRequestConfiguration
public RequestConfiguration getRequestConfiguration()
Gets the RequestConfiguration object in use by this task.- Specified by:
getRequestConfiguration
in interfaceRemoteResource
- Returns:
- the RequestConfiguration object, or null if none has been set
- Since:
- 100.1.0
- See Also:
RequestConfiguration
-
getUri
public String getUri()
Gets the URI of this task. This is the URI of the online map.- Specified by:
getUri
in interfaceRemoteResource
- Returns:
- the URI of this task; may be null if the task is not loaded
- Since:
- 100.1.0
-
getOnlineMap
public ArcGISMap getOnlineMap()
Gets the online map to be taken offline.The online map will be of type
PortalItem.Type.WEBMAP
, either on ArcGIS Online or an on-premise ArcGIS Enterprise Portal.- Returns:
- the online map; may be null if the task is not loaded
- Since:
- 100.1.0
-
getPortalItem
public PortalItem getPortalItem()
Gets the portal item that specifies the map to be taken offline.The
PortalItem
will be of typePortalItem.Type.WEBMAP
, either on ArcGIS Online or an on-premise ArcGIS Enterprise Portal.- Returns:
- the portal item
- Since:
- 100.1.0
-
createDefaultGenerateOfflineMapParametersAsync
public ListenableFuture<GenerateOfflineMapParameters> createDefaultGenerateOfflineMapParametersAsync(Geometry areaOfInterest)
Executes an asynchronous operation to create a set of default parameters that can be used to take an online map offline. The result is a GenerateOfflineMapParameters object.The supported geometry types for the area of interest are
Envelope
andPolygon
. The area of interest must have a spatial reference.Where a
Polygon
is supplied, features and tiles will be filtered according to the polygon geometry, which can help reduce the size of the resulting offline map. Note that the filtered set of tiles may vary, depending on the underlying service.In the resultant GenerateOfflineMapParameters:
- minScale and maxScale are zero, which will cause the full range of scales supported by the service to be taken offline
- the itemInfo is initialized from the offline map task's portal item
- the itemInfo's thumbnail is copied from the portal item's thumbnail
- Parameters:
areaOfInterest
- the region of the online map that is to be taken offline; must be an Envelope or a Polygon and must have a spatial reference- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result; also allows
cancellation. Calling
get()
on the returned future may throw an ExecutionException with its cause set to:IOException
if a network request fails
- Throws:
IllegalArgumentException
- if areaOfInterest is null- Since:
- 100.1.0
- See Also:
generateOfflineMap(GenerateOfflineMapParameters, String)
-
createDefaultDownloadPreplannedOfflineMapParametersAsync
public ListenableFuture<DownloadPreplannedOfflineMapParameters> createDefaultDownloadPreplannedOfflineMapParametersAsync(PreplannedMapArea preplannedMapArea)
Executes an asynchronous operation to create a DownloadPreplannedOfflineMapParameters from the specified PreplannedMapArea.A convenience method to create
DownloadPreplannedOfflineMapParameters
with default values appropriate for taking the specified map area offline. The parameters will be populated using the values in the online map'sOfflineSettings
(if present).- Parameters:
preplannedMapArea
- the offline map area that is to be downloaded from the online map- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result
- Throws:
IllegalArgumentException
- if preplannedMapArea is null- Since:
- 100.5.0
-
createDefaultGenerateOfflineMapParametersAsync
public ListenableFuture<GenerateOfflineMapParameters> createDefaultGenerateOfflineMapParametersAsync(Geometry areaOfInterest, double minScale, double maxScale)
Executes an asynchronous operation to create a GenerateOfflineMapParameters from the specified area of interest, min scale, and max scale.The supported geometry types for the area of interest are
Envelope
andPolygon
. The area of interest must have a spatial reference.Where a
Polygon
is supplied, features and tiles will be filtered according to the polygon geometry, which can help reduce the size of the resulting offline map. Note that the filtered set of tiles may vary, depending on the underlying service.The returned
GenerateOfflineMapParameters
has its ItemInfo (seeGenerateOfflineMapParameters.getItemInfo()
) property initialized from the offline map task's portal item, if that is set. The ItemInfo's thumbnail will be copied from the portal item's thumbnail. The default parameters will be populated using the values in the online map'sOfflineSettings
(if present).- Parameters:
areaOfInterest
- a Geometry defining the area of interest; must be an Envelope or a Polygon and must have a spatial reference. SeeGenerateOfflineMapParameters.setAreaOfInterest(Geometry)
.minScale
- the minimum scale for offline tile caches. Use 0 to select all far out levels (those which are less detailed than the maxScale). SeeGenerateOfflineMapParameters.setMinScale(double)
.maxScale
- the maximum scale for offline tile caches. Use 0 to select all closer in levels (those which are more detailed than the minScale). SeeGenerateOfflineMapParameters.setMaxScale(double)
.- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result
- Throws:
IllegalArgumentException
- if areaOfInterest is null, or minScale or maxScale is negative- Since:
- 100.5.0
-
createGenerateOfflineMapParameterOverridesAsync
public ListenableFuture<GenerateOfflineMapParameterOverrides> createGenerateOfflineMapParameterOverridesAsync(GenerateOfflineMapParameters parameters)
Executes an asynchronous operation to create a GenerateOfflineMapParameterOverrides object that is populated to reflect the values in the provided GenerateOfflineMapParameters. The overrides may be inspected and modified to change the offline data before creating a job withgenerateOfflineMap(GenerateOfflineMapParameters, String, GenerateOfflineMapParameterOverrides)
.If there are errors with loading individual layers or tables, or they cannot be taken offline due to service settings, the outcome depends on the value of
GenerateOfflineMapParameters.isContinueOnErrors()
:- If
isContinueOnErrors
is true, the overrides correspond to the remaining layers and tables that can go offline. The resulting offline map will not contain the layers or tables which had errors. - If
isContinueOnErrors
is false, this operation will fail and callingget()
on the returned future will throw an ExecutionException with its cause set to the layer or table error that caused the failure.
To check upfront which layers or tables are valid for taking offline see
getOfflineMapCapabilitiesAsync(GenerateOfflineMapParameters)
.If the reference basemap directory is set (see
GenerateOfflineMapParameters.setReferenceBasemapDirectory(String)
), the overrides corresponding to online basemap layers will be omitted, since no basemap layers will be downloaded.- Parameters:
parameters
- the GenerateOfflineMapParameters from which the overrides will be populated- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result; also allows
cancellation. Calling
get()
on the returned future may throw an ExecutionException with its cause set to:IOException
if a network request fails
- Throws:
IllegalArgumentException
- if parameters is null- Since:
- 100.4.0
- If
-
getOfflineMapCapabilitiesAsync
public ListenableFuture<OfflineMapCapabilities> getOfflineMapCapabilitiesAsync(GenerateOfflineMapParameters parameters)
Executes an asynchronous operation to get theOfflineMapCapabilities
containing information on which layers will be included in an offline map.- Parameters:
parameters
- the parameters to be used for taking the map offline- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result; also allows
cancellation. Calling
get()
on the returned future may throw an ExecutionException with its cause set to:IOException
if a network request fails
- Throws:
IllegalArgumentException
- if parameters is null- Since:
- 100.1.0
-
generateOfflineMap
public GenerateOfflineMapJob generateOfflineMap(GenerateOfflineMapParameters parameters, String downloadDirectoryPath)
Creates aGenerateOfflineMapJob
that can be used to generate an offline map from an online map, using the specified parameters. The job will fail if the last directory in the download directory path cannot be created or is not empty.- Parameters:
parameters
- the parameters to be used for the generate offline map operationdownloadDirectoryPath
- The path to a folder where the map content is stored on the device. For example, to create a new mobile map packagemy_mobile_map_package
in a parent directory[my root path]/my_mobile_maps
, this property would be[my root path]/my_mobile_maps/my_mobile_map_package
.- Returns:
- a GenerateOfflineMapJob that will generate the offline map. The result is a GenerateOfflineMapResult object
if the job completed successfully. Note you must call
Job.start()
to start the Job. - Throws:
IllegalArgumentException
- if parameters is null, or if downloadDirectoryPath is null or empty- Since:
- 100.1.0
-
generateOfflineMap
public GenerateOfflineMapJob generateOfflineMap(GenerateOfflineMapParameters parameters, String downloadDirectoryPath, GenerateOfflineMapParameterOverrides parameterOverrides)
Creates aGenerateOfflineMapJob
that can be used to generate an offline map from an online map, using the specified parameters and overrides. The job will fail if the last directory in the download directory path cannot be created or is not empty.The
GenerateOfflineMapParameterOverrides
allows more control over the extracted data. UsecreateGenerateOfflineMapParameterOverridesAsync(GenerateOfflineMapParameters)
to create an instance ofGenerateOfflineMapParameterOverrides
.Some properties on GenerateOfflineMapParameters will be ignored when using GenerateOfflineMapParameterOverrides and replaced with equivalent properties for each service. The overridden properties are:
GenerateOfflineMapParameters.isIncludeBasemap()
GenerateOfflineMapParameters.getReturnLayerAttachmentOption()
GenerateOfflineMapParameters.getAttachmentSyncDirection()
GenerateOfflineMapParameters.isReturnSchemaOnlyForEditableLayers()
GenerateOfflineMapParameters.isDefinitionExpressionFilterEnabled()
GenerateOfflineMapParameters.getOnlineOnlyServicesOption()
- Parameters:
parameters
- the parameters to be used for the generate offline map operationdownloadDirectoryPath
- The path to a folder where the map content is stored on the device. For example, to create a new mobile map packagemy_mobile_map_package
in a parent directory[my root path]/my_mobile_maps
, this property would be[my root path]/my_mobile_maps/my_mobile_map_package
.parameterOverrides
- the overrides to the parameters- Returns:
- a GenerateOfflineMapJob that will generate the offline map. The result is a GenerateOfflineMapResult object
if the job completed successfully. Note you must call
Job.start()
to start the Job. - Throws:
IllegalArgumentException
- if parameters or parameterOverrides is null, or if downloadDirectoryPath is null or empty- Since:
- 100.4.0
-
getPreplannedMapAreasAsync
public ListenableFuture<List<PreplannedMapArea>> getPreplannedMapAreasAsync()
Executes an asynchronous operation to get a list of preplanned map areas. The result is an unmodifiable list of PreplannedMapArea objects, which is empty if there are no preplanned areas for this map.Note that calling this method will load the OfflineMapTask if it is not already loaded.
- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result; also allows
cancellation. Calling
get()
on the returned future may throw an ExecutionException with its cause set to:IOException
if a network request fails
- Since:
- 100.2.0
-
downloadPreplannedOfflineMap
@Deprecated public DownloadPreplannedOfflineMapJob downloadPreplannedOfflineMap(PreplannedMapArea area, String downloadDirectoryPath)
Deprecated.as of 100.10.0. Please usedownloadPreplannedOfflineMap(DownloadPreplannedOfflineMapParameters, String)
.This method does not support the scheduled updates workflow and will default to use
PreplannedUpdateMode.SYNC_WITH_FEATURE_SERVICES
.An instance of
DownloadPreplannedOfflineMapParameters
can be created and populated as required. Alternatively, the recommended workflow is to usecreateDefaultDownloadPreplannedOfflineMapParametersAsync(PreplannedMapArea)
and then make any adjustments. This will determine if scheduled updates are present and update the propertyDownloadPreplannedOfflineMapParameters.getUpdateMode()
appropriately.Returns a job that is used to download the specified preplanned map area of an online map.The job that is returned is dormant and needs to be explicitly started. The job will fail if the last directory in the download directory path cannot be created or is not empty.
- Parameters:
area
- specifies the offline map area to be downloadeddownloadDirectoryPath
- the path to a folder where the map content is stored on the device. For example, to create a new mobile map package "my_mobile_map_package" in a parent directory "[my root path]/my_mobile_maps", this property would be "[my root path]/my_mobile_maps/my_mobile_map_package".- Returns:
- a
DownloadPreplannedOfflineMapJob
to download an offline map area - Throws:
IllegalArgumentException
- if area is null, or if downloadDirectoryPath is null or empty- Since:
- 100.2.0
-
downloadPreplannedOfflineMap
@Deprecated public DownloadPreplannedOfflineMapJob downloadPreplannedOfflineMap(PreplannedMapArea area, String downloadDirectoryPath, boolean excludeBasemap)
Deprecated.As of 100.4.0, replaced bydownloadPreplannedOfflineMap(DownloadPreplannedOfflineMapParameters, String)
.Creates aDownloadPreplannedOfflineMapJob
that can be used to download the given preplanned map area of an online map. The job will fail if the last directory in the download directory path cannot be created or is not empty.If you exclude the map's basemap from the download the offline map's size will be smaller and consequently the download process will be faster. If you already have a basemap stored locally on your device you can add that to the offline map. The job that is returned is dormant and needs to be explicitly started. The job will fail if the last directory in the download directory path cannot be created or is not empty. Specifying exclude_basemap true will override the authored settings of preplanned map area and always exclude the basemap content.
- Parameters:
area
- specifies the offline map area to be downloadeddownloadDirectoryPath
- The path to a folder where the map content is stored on the device. For example, to create a new mobile map packagemy_mobile_map_package
in a parent directory[my root path]/my_mobile_maps
, this property would be[my root path]/my_mobile_maps/my_mobile_map_package
.excludeBasemap
- true to exclude the basemap from the offline map- Returns:
- a DownloadPreplannedOfflineMapJob that will download the preplanned map area. The result is a
DownloadPreplannedOfflineMapResult object if the job completed successfully. Note you must call
Job.start()
to start the Job. - Throws:
IllegalArgumentException
- if area is null, or if downloadDirectoryPath is null or empty- Since:
- 100.2.0
-
downloadPreplannedOfflineMap
public DownloadPreplannedOfflineMapJob downloadPreplannedOfflineMap(DownloadPreplannedOfflineMapParameters parameters, String downloadDirectoryPath)
Creates aDownloadPreplannedOfflineMapJob
that can be used to download the preplanned map area specified by the given parameters object. The job will fail if the last directory in the download directory path cannot be created or is not empty.- Parameters:
parameters
- specifies parameters for the job including the preplanned map area to be downloadeddownloadDirectoryPath
- The path to a folder where the map content is stored on the device. For example, to create a new mobile map packagemy_mobile_map_package
in a parent directory[my root path]/my_mobile_maps
, this property would be[my root path]/my_mobile_maps/my_mobile_map_package
.- Returns:
- a DownloadPreplannedOfflineMapJob that will download the preplanned map area. The result is a
DownloadPreplannedOfflineMapResult object if the job completed successfully. Note you must call
Job.start()
to start the Job. - Throws:
IllegalArgumentException
- if parameters is null, or if downloadDirectoryPath is null or empty- Since:
- 100.4.0
-
getLoadStatus
public LoadStatus getLoadStatus()
Description copied from interface:Loadable
Returns theLoadStatus
of the loadable resource.- Specified by:
getLoadStatus
in interfaceLoadable
- Returns:
- the LoadStatus of the loadable resource
-
getLoadError
public ArcGISRuntimeException getLoadError()
Description copied from interface:Loadable
Returns the most recent error that was encountered when the loadable resource transitioned to theLoadStatus.FAILED_TO_LOAD
state, either due to calling theLoadable.loadAsync()
orLoadable.retryLoadAsync()
method.If the resource subsequently transitions to
LoadStatus.LOADED
(for example, if a call toretryLoadAsync
completes successfully) the error is cleared out.- Specified by:
getLoadError
in interfaceLoadable
- Returns:
- the most recent error that was encountered when the loadable resource transitioned to the
LoadStatus.FAILED_TO_LOAD
state.
-
cancelLoad
public void cancelLoad()
Description copied from interface:Loadable
Cancels loading metadata for the object.Cancels loading the metadata if the object is loading, and always invokes the done loading listener.
A load operation that is in progress (
LoadStatus.LOADING
state) can be cancelled by calling this method and the resource will transition fromLoadStatus.LOADING
toLoadStatus.FAILED_TO_LOAD
state. If the load operation was successfully cancelled, a CancellationException will be returned fromLoadable.getLoadError()
.Cancellation should be used carefully because all enqueued done loading listeners for that resource instance will get invoked with an error stating that the operation was cancelled. Thus, one component in the application can cancel the load operation initiated by other components.
This method does nothing if the resource is not in
LoadStatus.LOADING
state.- Specified by:
cancelLoad
in interfaceLoadable
-
loadAsync
public void loadAsync()
Description copied from interface:Loadable
Loads the metadata of the loadable resource asynchronously.The load status changes from
LoadStatus.NOT_LOADED
toLoadStatus.LOADING
. A listener can be added viaLoadable.addDoneLoadingListener(java.lang.Runnable)
that is invoked upon completion of the asynchronous load operation.If the load operation completes successfully, the load status will be
LoadStatus.LOADED
, which means the resource has loaded its metadata.If the load operation failed, the load status will be
LoadStatus.FAILED_TO_LOAD
and the error can be retrieved by callingLoadable.getLoadError()
.This method can be called concurrently and repeatedly, but only one attempt is ever made to perform the load operation. If a load operation is already in progress (
LoadStatus.LOADING
state) whenloadAsync
is called, it simply piggy-backs on the outstanding operation and the done loading listener added to the loadable resource is enqueued to be invoked when that operation completes. If the operation has already completed (LoadStatus.LOADED
orLoadStatus.FAILED_TO_LOAD
state) whenloadAsync
is called, the done loading listener is immediately invoked when added to the loadable resource.If a loadable resource has failed to load, calling
loadAsync
on it subsequently will not change its state. The done loading listener will be invoked immediately when added to the loadable resource. In order to retry loading the resource,Loadable.retryLoadAsync()
needs to be used.A load operation that is in progress (
LoadStatus.LOADING
state) can be cancelled by callingLoadable.cancelLoad()
.
-
retryLoadAsync
public void retryLoadAsync()
Description copied from interface:Loadable
Loads or retries loading metadata for the object asynchronously.Will retry loading the metadata if the object's load status is
LoadStatus.FAILED_TO_LOAD
. Will load the object if it is not loaded. Will not retry to load the object if the object is loaded.For more details on the load process see
Loadable.loadAsync()
.- Specified by:
retryLoadAsync
in interfaceLoadable
-
addDoneLoadingListener
public void addDoneLoadingListener(Runnable listener)
Description copied from interface:Loadable
Adds a listener to the loadable resource that is invoked when loading has completed.The listener may be added at any point, whether the loadable resource has already completed loading or not.
- For resources that are not loaded when the listener is added (LoadStatus is NOT_LOADED or LOADING): When the resource completes loading, the listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.
- For resources that are already loaded when the listener is added (LoadStatus is LOADED or FAILED_TO_LOAD): The listener will be called immediately, on the current thread.
Alternatively, to be notified when there is any change in the load status, use the
Loadable.addLoadStatusChangedListener(LoadStatusChangedListener)
method instead.- Specified by:
addDoneLoadingListener
in interfaceLoadable
- Parameters:
listener
- a Runnable that is invoked upon completion of the load operation
-
removeDoneLoadingListener
public boolean removeDoneLoadingListener(Runnable listener)
Description copied from interface:Loadable
Removes a done loading listener from the loadable resource.- Specified by:
removeDoneLoadingListener
in interfaceLoadable
- Parameters:
listener
- the listener to be removed- Returns:
- true if the listener was removed, otherwise false
-
addLoadStatusChangedListener
public void addLoadStatusChangedListener(LoadStatusChangedListener listener)
Description copied from interface:Loadable
Adds aLoadStatusChangedListener
to the loadable resource that is invoked whenever the load status changes.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.
The listener will not be called if added to a loadable resource that has already completed loading. To be notified when a loadable resource has completed loading, including if the resource is already loaded when the listener is added, use the
Loadable.addDoneLoadingListener(Runnable)
method.- Specified by:
addLoadStatusChangedListener
in interfaceLoadable
- Parameters:
listener
- theLoadStatusChangedListener
to be added
-
removeLoadStatusChangedListener
public boolean removeLoadStatusChangedListener(LoadStatusChangedListener listener)
Description copied from interface:Loadable
Removes aLoadStatusChangedListener
from the loadable resource.- Specified by:
removeLoadStatusChangedListener
in interfaceLoadable
- Parameters:
listener
- theLoadStatusChangedListener
to be removed- Returns:
- true if the listener was removed, otherwise false
-
-