Class UtilityNetwork
- java.lang.Object
-
- com.esri.arcgisruntime.utilitynetworks.UtilityNetwork
-
- All Implemented Interfaces:
RemoteResource
,Loadable
public final class UtilityNetwork extends Object implements Loadable, RemoteResource
Defines a utility network.- Since:
- 100.6.0
-
-
Constructor Summary
Constructors Constructor Description UtilityNetwork(String url)
Creates a utility network from the provided URL to the feature service.UtilityNetwork(String url, ArcGISMap map)
Creates a utility network with the URL to the feature service and a map.
-
Method Summary
All Methods Instance Methods Concrete 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.UtilityElement
createElement(ArcGISFeature arcGISFeature)
Creates aUtilityElement
from anArcGISFeature
.UtilityElement
createElement(ArcGISFeature arcGISFeature, UtilityTerminal terminal)
UtilityElement
createElement(UtilityAssetType assetType, UUID globalId)
Creates aUtilityElement
from aUtilityAssetType
and a global ID.UtilityElement
createElement(UtilityAssetType assetType, UUID globalId, UtilityTerminal terminal)
ListenableFuture<List<ArcGISFeature>>
fetchFeaturesForElementsAsync(Iterable<UtilityElement> utilityElements)
Executes an asynchronous operation to fetch the features that are referenced by a given set of UtilityElements.ListenableFuture<List<UtilityAssociation>>
getAssociationsAsync(Envelope extent)
Returns an unmodifiable list of allUtilityAssociation
objects (with their geometry) present in the geodatabase for a givenEnvelope
.ListenableFuture<List<UtilityAssociation>>
getAssociationsAsync(Envelope extent, UtilityAssociationType type)
Returns an unmodifiable list of allUtilityAssociation
objects (with their geometry) of typeUtilityAssociationType
present in the geodatabase for a givenEnvelope
.ListenableFuture<List<UtilityAssociation>>
getAssociationsAsync(UtilityElement element)
Returns an unmodifiable list of allUtilityAssociation
objects present in the geodatabase for a givenUtilityElement
.ListenableFuture<List<UtilityAssociation>>
getAssociationsAsync(UtilityElement element, UtilityAssociationType type)
Returns an unmodifiable list of allUtilityAssociation
objects of typeUtilityAssociationType
present in the geodatabase for a givenUtilityElement
.Credential
getCredential()
Gets theCredential
that is set on the network-enabled resource.UtilityNetworkDefinition
getDefinition()
Gets the definition of the utility network.Geodatabase
getGeodatabase()
Gets theGeodatabase
that contains this UtilityNetwork.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.String
getName()
Gets the name of the utility network.RequestConfiguration
getRequestConfiguration()
Gets theRequestConfiguration
used to modify the parameters of network requests made by thisRemoteResource
.ServiceGeodatabase
getServiceGeodatabase()
Gets theServiceGeodatabase
of the UtilityNetwork.String
getUri()
Returns the URL used to create the utility network.void
loadAsync()
Loads the metadata of the loadable resource asynchronously.ListenableFuture<List<UtilityNamedTraceConfiguration>>
queryNamedTraceConfigurationsAsync(UtilityNamedTraceConfigurationQueryParameters queryParameters)
Returns a list ofUtilityNamedTraceConfiguration
from the utility network.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 aCredential
to be used by the network-enabled resource in the event of an authentication challenge.void
setRequestConfiguration(RequestConfiguration requestConfiguration)
Sets theRequestConfiguration
used to modify the parameters of network requests made by thisRemoteResource
.ListenableFuture<List<UtilityTraceResult>>
traceAsync(UtilityTraceParameters traceParameters)
Begins a trace with the suppliedUtilityTraceParameters
.
-
-
-
Constructor Detail
-
UtilityNetwork
public UtilityNetwork(String url)
Creates a utility network from the provided URL to the feature service.- Parameters:
url
- the URL to the feature service- Throws:
IllegalArgumentException
- if url is null or empty- Since:
- 100.6.0
-
UtilityNetwork
public UtilityNetwork(String url, ArcGISMap map)
Creates a utility network with the URL to the feature service and a map.Creates a utility network associated with a particular service, using the same
FeatureTable
objects in use byFeatureLayer
objects within theArcGISMap
. This lets anyUtilityElement
orArcGISFeature
objects the UtilityNetwork creates or uses be associated with those existingFeatureTable
andFeatureLayer
. Usually used when instantiating a UtilityNetwork object from a web map.- Parameters:
url
- the URL to the feature servicemap
- An ArcGISMap that provides FeatureTables to be reused by the utility network- Throws:
IllegalArgumentException
- if url is null or emptyIllegalArgumentException
- if the map is null- Since:
- 100.6.0
-
-
Method Detail
-
getDefinition
public UtilityNetworkDefinition getDefinition()
Gets the definition of the utility network.- Returns:
- the definition
- Since:
- 100.6.0
-
getName
public String getName()
Gets the name of the utility network. This property is empty whenUtilityNetwork
is not retrieved from aGeodatabase
.- Returns:
- the name of the utility network
- Since:
- 100.8.0
-
getGeodatabase
public Geodatabase getGeodatabase()
Gets theGeodatabase
that contains this UtilityNetwork.The
Geodatabase
that contains this UtilityNetwork and is also used by theGeodatabaseFeatureTable
inUtilityNetworkDefinition.getNetworkSources()
.Use this property to manage transactions, sync edits, or access tables participating in this UtilityNetwork.
This property has a value when the UtilityNetwork is retrieved from a
Geodatabase
; otherwise, when created using any of the constructors, this property is null.Note that calling
Geodatabase.close()
on aGeodatabase
that contains this UtilityNetwork will render this UtilityNetwork unusable. An attempt to create an element, get associations, get features from elements, or perform a trace after thisGeodatabase
is closed will throw anArcGISRuntimeException
.- Returns:
- the
Geodatabase
that contains this UtilityNetwork, or null if none - Since:
- 100.11.0
-
getUri
public String getUri()
Returns the URL used to create the utility network.- Specified by:
getUri
in interfaceRemoteResource
- Returns:
- the URL used to create the utility network
- Since:
- 100.6.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
-
getCredential
public Credential getCredential()
Description copied from interface:RemoteResource
Gets theCredential
that is set on the network-enabled resource.Only applicable if the resource is secured.
- Specified by:
getCredential
in interfaceRemoteResource
- Returns:
- the Credential, or null if there is none
-
setCredential
public void setCredential(Credential credential)
Description copied from interface:RemoteResource
Sets aCredential
to be used by the network-enabled resource in the event of an authentication challenge. The default credential is null.Only applicable if the resource is secured.
- Specified by:
setCredential
in interfaceRemoteResource
- Parameters:
credential
- the Credential to be used for authentication
-
getRequestConfiguration
public RequestConfiguration getRequestConfiguration()
Description copied from interface:RemoteResource
Gets theRequestConfiguration
used to modify the parameters of network requests made by thisRemoteResource
.- Specified by:
getRequestConfiguration
in interfaceRemoteResource
- Returns:
- the
RequestConfiguration
used to modify network requests
-
setRequestConfiguration
public void setRequestConfiguration(RequestConfiguration requestConfiguration)
Description copied from interface:RemoteResource
Sets theRequestConfiguration
used to modify the parameters of network requests made by thisRemoteResource
. If not set, the globalRequestConfiguration
will be used (seeRequestConfiguration.getGlobalRequestConfiguration()
).- Specified by:
setRequestConfiguration
in interfaceRemoteResource
- Parameters:
requestConfiguration
- the RequestConfiguration used to modify network requests
-
createElement
public UtilityElement createElement(ArcGISFeature arcGISFeature)
Creates aUtilityElement
from anArcGISFeature
.If the feature's
UtilityAssetType
supports aUtilityTerminalConfiguration
, a defaultUtilityTerminal
will be assigned.- Parameters:
arcGISFeature
- the Feature from which this UtilityElement is to be created- Returns:
- the UtilityElement created from the given feature
- Throws:
IllegalArgumentException
- if arcGISFeature is null- Since:
- 100.7.0
-
createElement
public UtilityElement createElement(ArcGISFeature arcGISFeature, UtilityTerminal terminal)
Creates aUtilityElement
from anArcGISFeature
and an optionalUtilityTerminal
.The terminal parameter can be null as it is not necessary if the Feature is an edge in the network. If the optional
UtilityTerminal
is not supplied, and the feature'sUtilityAssetType
supports aUtilityTerminalConfiguration
, a defaultUtilityTerminal
will be assigned.- Parameters:
arcGISFeature
- the Feature from which this UtilityElement is to be createdterminal
- the terminal for a junction feature- Returns:
- the UtilityElement created from the given feature and terminal
- Throws:
IllegalArgumentException
- if arcGISFeature is null- Since:
- 100.6.0
-
createElement
public UtilityElement createElement(UtilityAssetType assetType, UUID globalId)
Creates aUtilityElement
from aUtilityAssetType
and a global ID.If the
UtilityAssetType
supports aUtilityTerminalConfiguration
, a defaultUtilityTerminal
will be assigned.- Parameters:
assetType
- the asset type of the Feature from which this UtilityElement is createdglobalId
- the global ID of the Feature from which this UtilityElement is to be created- Returns:
- the UtilityElement created from the given asset type and global id
- Throws:
IllegalArgumentException
- if assetType is nullIllegalArgumentException
- if globalId is null- Since:
- 100.7.0
-
createElement
public UtilityElement createElement(UtilityAssetType assetType, UUID globalId, UtilityTerminal terminal)
Creates aUtilityElement
from aUtilityAssetType
, a global ID and an optionalUtilityTerminal
.The terminal parameter can be null as it is not necessary if the Feature is an edge in the network. If the optional
UtilityTerminal
is not supplied, and the feature'sUtilityAssetType
supports aUtilityTerminalConfiguration
, a defaultUtilityTerminal
will be assigned.- Parameters:
assetType
- the asset type of the Feature from which this UtilityElement is createdglobalId
- the global ID of the Feature from which this UtilityElement is to be createdterminal
- the terminal for a junction feature- Returns:
- the UtilityElement created from the given asset type, global id and terminal
- Throws:
IllegalArgumentException
- if assetType is nullIllegalArgumentException
- if globalId is null- Since:
- 100.6.0
-
traceAsync
public ListenableFuture<List<UtilityTraceResult>> traceAsync(UtilityTraceParameters traceParameters)
Begins a trace with the suppliedUtilityTraceParameters
.The result is an unmodifiable list of UtilityTraceResult objects containing
UtilityElement
if the result type specified byUtilityTraceParameters.getResultTypes()
isUtilityTraceResult.Type.ELEMENTS
.If the value returned by
UtilityTraceParameters.getTraceType()
is a subnetwork-based trace, it must have aUtilityDomainNetwork
set in theUtilityTraceConfiguration
returned fromUtilityTraceParameters.getTraceConfiguration()
.- Parameters:
traceParameters
- the object that holds all necessary parameters to run a trace- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation
- Throws:
IllegalArgumentException
- if traceParameters is null- Since:
- 100.6.0
-
fetchFeaturesForElementsAsync
public ListenableFuture<List<ArcGISFeature>> fetchFeaturesForElementsAsync(Iterable<UtilityElement> utilityElements)
Executes an asynchronous operation to fetch the features that are referenced by a given set of UtilityElements. The result is an unmodifiable list of loaded ArcGISFeature objects.- Parameters:
utilityElements
- the set of elements for which to get the matching features- Returns:
- a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation
- Throws:
IllegalArgumentException
- if utilityElements is null or empty- Since:
- 100.6.0
-
getAssociationsAsync
public ListenableFuture<List<UtilityAssociation>> getAssociationsAsync(Envelope extent)
Returns an unmodifiable list of allUtilityAssociation
objects (with their geometry) present in the geodatabase for a givenEnvelope
.The result is a list of connectivity and structural attachment associations. Containment associations are not returned because no geometric relationship is defined between a container and its contents. The method does not return a complete picture of connectivity; features that are connected by geometric coincidence are not returned. Note that the list returned can contain associations that have not yet been validated and are therefore not yet included in the topological index.
- Parameters:
extent
- theEnvelope
that defines the area for which to return associations- Returns:
- a list of all the
UtilityAssociation
objects (with their geometry) if available. Otherwise, an empty list is returned. - Throws:
IllegalArgumentException
- if extent is null- Since:
- 100.8.0
-
getAssociationsAsync
public ListenableFuture<List<UtilityAssociation>> getAssociationsAsync(Envelope extent, UtilityAssociationType type)
Returns an unmodifiable list of allUtilityAssociation
objects (with their geometry) of typeUtilityAssociationType
present in the geodatabase for a givenEnvelope
.Containment associations are not returned because no geometric relationship is defined between a container and its contents; consider using
getAssociationsAsync(UtilityElement, UtilityAssociationType)
instead. The method does not return a complete picture of connectivity; features that are connected by geometric coincidence are not returned. Note that the list returned can contain associations that have not yet been validated and are therefore not yet included in the topological index.- Parameters:
extent
- theEnvelope
that defines the area for which to return associationstype
- theUtilityAssociationType
of associations to return- Returns:
- a list of all the
UtilityAssociation
objects (with their geometry) of the specified type if available. Otherwise, an empty list is returned. - Throws:
IllegalArgumentException
- if extent or type is null- Since:
- 100.8.0
-
getAssociationsAsync
public ListenableFuture<List<UtilityAssociation>> getAssociationsAsync(UtilityElement element)
Returns an unmodifiable list of allUtilityAssociation
objects present in the geodatabase for a givenUtilityElement
.The result is a list of all associations – connectivity associations, containment associations, structural attachment associations – that include the given
UtilityElement
object. The method does not return a complete picture of connectivity; features that are connected by geometric coincidence are not returned. Note that the list returned can contain associations that have not yet been validated and are therefore not yet included in the topological index.- Parameters:
element
- theUtilityElement
whose associations are to be returned- Returns:
- an unmodifiable list of all the
UtilityAssociation
objects if available. Otherwise, an empty list is returned. - Throws:
IllegalArgumentException
- if element is null- Since:
- 100.7.0
-
getAssociationsAsync
public ListenableFuture<List<UtilityAssociation>> getAssociationsAsync(UtilityElement element, UtilityAssociationType type)
Returns an unmodifiable list of allUtilityAssociation
objects of typeUtilityAssociationType
present in the geodatabase for a givenUtilityElement
.The method does not return a complete picture of connectivity; features that are connected by geometric coincidence are not returned. Note that the list returned can contain associations that have not yet been validated and are therefore not yet included in the topological index.
- Parameters:
element
- theUtilityElement
whose associations are to be returnedtype
- theUtilityAssociationType
of associations to return- Returns:
- a list of all the
UtilityAssociation
objects of the specified type if available. Otherwise, an empty list is returned - Throws:
IllegalArgumentException
- if element is nullIllegalArgumentException
- if type is null- Since:
- 100.7.0
-
queryNamedTraceConfigurationsAsync
public ListenableFuture<List<UtilityNamedTraceConfiguration>> queryNamedTraceConfigurationsAsync(UtilityNamedTraceConfigurationQueryParameters queryParameters)
Returns a list ofUtilityNamedTraceConfiguration
from the utility network.- Parameters:
queryParameters
- optional query parameter to filter the results, may be null- Returns:
- a
ListenableFuture<List<UtilityNamedTraceConfiguration>>
- Since:
- 100.11.0
- See Also:
UtilityNamedTraceConfigurationQueryParameters
-
getServiceGeodatabase
public ServiceGeodatabase getServiceGeodatabase()
Gets theServiceGeodatabase
of the UtilityNetwork.The ServiceGeodatabase is used by the
ServiceFeatureTable
inUtilityNetworkDefinition.getNetworkSource(String)
. Use this property to switch to a branch version, manage edits, or query related records of tables participating in this UtilityNetwork.This property is null until the UtilityNetwork is loaded. The
ArcGISMap
that was used to create this UtilityNetwork provides this ServiceGeodatabase. When no matching ServiceGeodatabase is found in the ArcGISMap, this UtilityNetwork will create and load a ServiceGeodatabase connected to the default version inFeatureServiceSessionType.TRANSIENT
mode.Note that calling
ServiceGeodatabase.closeAsync()
on a ServiceGeodatabase that is used by a UtilityNetwork will render this UtilityNetwork unusable. An attempt to create an element, get associations, get features from elements, or perform a trace after this ServiceGeodatabase is closed will fail with anArcGISRuntimeException
.- Returns:
- the ServiceGeodatabase of the UtilityNetwork
- Since:
- 100.10.0
-
-