Class ArcGISMapImageLayer
- java.lang.Object
-
- com.esri.arcgisruntime.layers.Layer
-
- com.esri.arcgisruntime.layers.ImageAdjustmentLayer
-
- com.esri.arcgisruntime.layers.ArcGISMapImageLayer
-
- All Implemented Interfaces:
TimeAware
,RemoteResource
,LayerContent
,Loadable
public final class ArcGISMapImageLayer extends ImageAdjustmentLayer implements RemoteResource, TimeAware
Displays data from an ArcGIS Map service by using dynamically generated map images.ArcGIS map image layer displays maps from an ArcGIS map server. A map service can contain multiple layers, rendered by the server each time a request is made and returned to the client as a single raster image. While the image itself does not contain information about the features it displays, you can get the underlying data (service feature table) for each sublayer. This layer supports time-based filtering.
Functional characteristics
Map images are created and returned by the server on every request, so they always show the latest data at the time of the request. Characteristics of the image, such as brightness, contrast, gamma, and opacity can be specified. You can also control the visibility and symbols of sublayers and filter data with layer definition expressions. The spatial reference can be changed from the service's default and the service will re-project each image on the fly.
The underlying service feature table for each map image sublayer (or for non-spatial tables used in the service) can be accessed. These tables can be queried using any valid combination of attribute, spatial, and temporal criteria. You can also query for summary statistics or to find related features in other tables.
Performance characteristics
The map service creates map images on the fly. Rendering time depends on the amount and complexity of the data in the map. This will typically be slower than fetching the equivalent map as pre-rendered tiles. Because the server renders the map, map image layers require less processing time on the client than similar maps rendered locally.
ArcGIS map image layers are good candidates for showing features that change periodically over time, or that require some sort of filtering by the user. Although rendering occurs on the server, the client has access to service feature tables for all sublayers (as well as non-spatial tables and relationships).
Example for working with data from a ArcGIS Map Image Layer
// create a MapImageLayer with dynamically generated map images final ArcGISMapImageLayer mapImageLayer = new ArcGISMapImageLayer("http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer"); // Add a listener that is invoked when layer loading has completed. mapImageLayer.addDoneLoadingListener(() -> { if (mapImageLayer.getLoadStatus() == LoadStatus.LOADED) { ArcGISMapServiceInfo mapServiceInfo = mapImageLayer.getMapServiceInfo(); // work with map service info here } }); // create an empty map instance ArcGISMap map = new ArcGISMap(); // add map image layer as operational layer map.getOperationalLayers().add(mapImageLayer); // set the map to be displayed in this view mapView.setMap(map);
The layer is loaded when displayed in aMapView
; if using the layer without a MapView, for example reading the map service metadata, call theLayer.loadAsync()
method. Use the layer done loading event to determine when the layer is ready, and check the loaded status before using the layer.- Since:
- 100.0.0
- See Also:
ArcGISMapServiceInfo
,Layer
,ArcGISSublayer
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
ArcGISMapImageLayer.ImageFormat
Defines image formats supported by a map image service.
-
Constructor Summary
Constructors Constructor Description ArcGISMapImageLayer(PortalItem portalItem)
Creates a new ArcGISMapImageLayer based on a map service PortalItem.ArcGISMapImageLayer(String url)
Creates a new ArcGISMapImageLayer from a map service or map service portal item at the given URL.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
Adds a listener that will fire when there is a change to the full time extent.ArcGISMapImageLayer
copy()
Creates a deep copy of this ArcGISMapImageLayer instance.Credential
getCredential()
Gets the credential used to authenticate the user with the map service.TimeExtent
getFullTimeExtent()
Returns the full time extent of the object.String
getGeodatabaseVersion()
Gets the version that this geodatabase is using.ArcGISMapImageLayer.ImageFormat
getImageFormat()
Gets the image format being used to generate map images on this layer.ArcGISMapServiceInfo
getMapServiceInfo()
Gets the map service info.long
getRefreshInterval()
Gets the refresh interval in milliseconds.RequestConfiguration
getRequestConfiguration()
Gets the RequestConfiguration object that contains parameters used when making a request by this layer.SublayerList
getSublayers()
Gets the sublayers that make up this map image layer.List<ServiceFeatureTable>
getTables()
Gets a list of tables in the map image layer.TimeValue
getTimeInterval()
Returns the suggested time slider step size for this time aware object.TimeValue
getTimeOffset()
Returns the time offset applied to this object.String
getUri()
Gets the web address of the map service resource.boolean
isTimeFilteringEnabled()
Returns whether or not the object must use the time extent defined on the owning GeoView to filter its data.boolean
isTimeFilteringSupported()
Returns whether or not the object supports filtering its contents by time values with the extent set on the owning GeoView.ListenableFuture<Void>
loadTablesAndLayersAsync()
Loads all of the map service's sublayers and non spatial tables.boolean
removeFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
Removes a full time extent changed listener.void
resetSublayers()
Resets the sublayers of a map image layer to the default values defined by the service.void
setCredential(Credential credential)
Sets the credential used to authenticate the user with the map service.void
setGeodatabaseVersion(String geodatabaseVersion)
Sets the version that this geodatabase is using.void
setImageFormat(ArcGISMapImageLayer.ImageFormat imageFormat)
Sets the image format being used to generate map images on this layer.void
setIsTimeFilteringEnabled(boolean enabled)
Enables or disables whether the object must use the time extent defined on the owning GeoView to filter its data.void
setRefreshInterval(long refreshIntervalMilliseconds)
Sets the refresh interval in milliseconds.void
setRequestConfiguration(RequestConfiguration requestConfiguration)
Sets the configuration parameters used for sending a network request using this layer object.void
setTimeOffset(TimeValue timeOffset)
Sets a time offset for this object.-
Methods inherited from class com.esri.arcgisruntime.layers.ImageAdjustmentLayer
getBrightness, getContrast, getGamma, setBrightness, setContrast, setGamma
-
Methods inherited from class com.esri.arcgisruntime.layers.Layer
addDoneLoadingListener, addLoadStatusChangedListener, addVisibilityChangedListener, cancelLoad, canChangeVisibility, canShowInLegend, fetchLegendInfosAsync, getAttribution, getDescription, getFullExtent, getId, getItem, getLoadError, getLoadStatus, getMaxScale, getMinScale, getName, getOpacity, getSpatialReference, getSubLayerContents, isIdentifyEnabled, isVisible, isVisibleAtScale, loadAsync, removeDoneLoadingListener, removeLoadStatusChangedListener, removeVisibilityChangedListener, retryLoadAsync, setCanShowInLegend, setDescription, setId, setMaxScale, setMinScale, setName, setOpacity, setVisible
-
-
-
-
Constructor Detail
-
ArcGISMapImageLayer
public ArcGISMapImageLayer(PortalItem portalItem)
Creates a new ArcGISMapImageLayer based on a map service PortalItem.If the portal item argument is not in
LoadStatus#LOADED
state it will be loaded automatically when this ArcGISMapImageLayer instance is loaded.- Parameters:
portalItem
- a map service PortalItem- Throws:
IllegalArgumentException
- if portalItem is null- Since:
- 100.0.0
-
ArcGISMapImageLayer
public ArcGISMapImageLayer(String url)
Creates a new ArcGISMapImageLayer from a map service or map service portal item at the given URL.To use a credential, call
setCredential(Credential)
after this constructor and before loading or using this layer.- Parameters:
url
- the map service or portal item URL- Throws:
IllegalArgumentException
- if the URL is null or empty- Since:
- 100.0.0
-
-
Method Detail
-
copy
public ArcGISMapImageLayer copy()
Creates a deep copy of this ArcGISMapImageLayer instance.- Returns:
- a deep copy of this ArcGISMapImageLayer instance, which means that copies of all fields of this layer are made including its loading state
- Since:
- 100.1.0
-
setCredential
public void setCredential(Credential credential)
Sets the credential used to authenticate the user with the map service.- Specified by:
setCredential
in interfaceRemoteResource
- Parameters:
credential
- the credential used to authenticate the user with the map service.- Since:
- 100.0.0
-
getCredential
public Credential getCredential()
Gets the credential used to authenticate the user with the map service.- Specified by:
getCredential
in interfaceRemoteResource
- Returns:
- the credential used to authenticate the user with the map service
- Since:
- 100.0.0
-
setRequestConfiguration
public void setRequestConfiguration(RequestConfiguration requestConfiguration)
Sets the configuration parameters used for sending a network request using this layer object. 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 that contains parameters used when making a request by this layer.- Specified by:
getRequestConfiguration
in interfaceRemoteResource
- Returns:
- the RequestConfiguration object or default vales if nothing was set
- Since:
- 100.0.0
-
getGeodatabaseVersion
public String getGeodatabaseVersion()
Gets the version that this geodatabase is using.- Returns:
- version of the geodatabase
- Since:
- 100.0.0
-
setGeodatabaseVersion
public void setGeodatabaseVersion(String geodatabaseVersion)
Sets the version that this geodatabase is using.- Parameters:
geodatabaseVersion
- the new geodatabase version- Since:
- 100.0.0
-
getUri
public String getUri()
Gets the web address of the map service resource.- Specified by:
getUri
in interfaceRemoteResource
- Returns:
- the URL of the map service
- Since:
- 100.0.0
-
getImageFormat
public ArcGISMapImageLayer.ImageFormat getImageFormat()
Gets the image format being used to generate map images on this layer.- Returns:
- the image format being used to generate images
- Since:
- 100.0.0
-
setImageFormat
public void setImageFormat(ArcGISMapImageLayer.ImageFormat imageFormat)
Sets the image format being used to generate map images on this layer.- Parameters:
imageFormat
- the image format to use when generating images- Since:
- 100.0.0
-
getMapServiceInfo
public ArcGISMapServiceInfo getMapServiceInfo()
Gets the map service info.The map service info accesses information about the map image layer for read only use.
- Returns:
- the map service info
- Since:
- 100.0.0
-
getSublayers
public SublayerList getSublayers()
Gets the sublayers that make up this map image layer.The sublayers will only be requested the first time, sequential calls will return the original list of sublayers.
- Returns:
- the sub layers from this image layer
- Since:
- 100.0.0
-
resetSublayers
public void resetSublayers()
Resets the sublayers of a map image layer to the default values defined by the service.After this call, any changes to the sublayers (either by using an ArcGISMapImageSublayer setter or by changing the sublayer collections) are lost. The sublayer hierarchy returns to its initial state (defined by the service) and image requests to display the layer will no longer use the dynamic layer capabilities of the service.
- Since:
- 100.1.0
- See Also:
ArcGISSublayer.getSublayers()
-
getRefreshInterval
public long getRefreshInterval()
Gets the refresh interval in milliseconds. The refresh interval is the time between automatic layer requests. A value of zero means the layer is never refreshed. The default value is zero.- Returns:
- the refresh interval in milliseconds
- Since:
- 100.1.0
-
setRefreshInterval
public void setRefreshInterval(long refreshIntervalMilliseconds)
Sets the refresh interval in milliseconds. The refresh interval is the time between automatic layer requests. A value of zero means the layer is never refreshed. The default value is zero.- Parameters:
refreshIntervalMilliseconds
- the refresh interval in milliseconds- Throws:
IllegalArgumentException
- if milliseconds is less than zero- Since:
- 100.1.0
-
getTables
public List<ServiceFeatureTable> getTables()
Gets a list of tables in the map image layer.The collection of tables is specific to this map image layer. Tables are not loaded by default. Tables are loaded internally when asynchronous operations like query are performed. Alternatively, they can be loaded by calling
loadTablesAndLayersAsync()
.- Returns:
- an unmodifiable list of service feature tables
- Since:
- 100.3.0
-
loadTablesAndLayersAsync
public ListenableFuture<Void> loadTablesAndLayersAsync()
Loads all of the map service's sublayers and non spatial tables.- Returns:
- a ListenableFuture to load the tables and sublayers asynchronously. Add a listener to the Future to know when the loading is done.
- Since:
- 100.3.0
-
getFullTimeExtent
public TimeExtent getFullTimeExtent()
Description copied from interface:TimeAware
Returns the full time extent of the object. Will be null if the object is not time aware.- Specified by:
getFullTimeExtent
in interfaceTimeAware
- Returns:
- the time extent, or null if the object is not time aware
-
getTimeInterval
public TimeValue getTimeInterval()
Description copied from interface:TimeAware
Returns the suggested time slider step size for this time aware object. Can be null if no time interval is suggested for this time aware object.- Specified by:
getTimeInterval
in interfaceTimeAware
- Returns:
- the time interval, or null if there is no time interval
-
getTimeOffset
public TimeValue getTimeOffset()
Description copied from interface:TimeAware
Returns the time offset applied to this object. The offset is subtracted from the time extent set on the owningGeoView
. This allows for data from different periods of time to be compared.- Specified by:
getTimeOffset
in interfaceTimeAware
- Returns:
- the time offset, or null if no offset has been set
-
isTimeFilteringEnabled
public boolean isTimeFilteringEnabled()
Description copied from interface:TimeAware
Returns whether or not the object must use the time extent defined on the owning GeoView to filter its data.- Specified by:
isTimeFilteringEnabled
in interfaceTimeAware
- Returns:
- true if time filtering is enabled; otherwise false
-
setIsTimeFilteringEnabled
public void setIsTimeFilteringEnabled(boolean enabled)
Description copied from interface:TimeAware
Enables or disables whether the object must use the time extent defined on the owning GeoView to filter its data.- Specified by:
setIsTimeFilteringEnabled
in interfaceTimeAware
- Parameters:
enabled
- true to enable time filtering; otherwise false
-
isTimeFilteringSupported
public boolean isTimeFilteringSupported()
Description copied from interface:TimeAware
Returns whether or not the object supports filtering its contents by time values with the extent set on the owning GeoView.- Specified by:
isTimeFilteringSupported
in interfaceTimeAware
- Returns:
- true if time filtering is supported; otherwise false
-
setTimeOffset
public void setTimeOffset(TimeValue timeOffset)
Description copied from interface:TimeAware
Sets a time offset for this object. The time offset is subtracted from the time extent set on the owningGeoView
. This allows for data from different periods of time to be compared. Can be null if there is no time offset.- Specified by:
setTimeOffset
in interfaceTimeAware
- Parameters:
timeOffset
- the time offset, or null if there is no time offset
-
addFullTimeExtentChangedListener
public void addFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
Description copied from interface:TimeAware
Adds a listener that will fire when there is a change to the full time extent.- Specified by:
addFullTimeExtentChangedListener
in interfaceTimeAware
- Parameters:
listener
- the listener to add
-
removeFullTimeExtentChangedListener
public boolean removeFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
Description copied from interface:TimeAware
Removes a full time extent changed listener.- Specified by:
removeFullTimeExtentChangedListener
in interfaceTimeAware
- Parameters:
listener
- the listener to remove- Returns:
- true if the listener was removed, otherwise false
-
-