Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.utilitynetworks

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

  • Property Details

  • Constructor Details

    • 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 by FeatureLayer objects within the ArcGISMap. This lets any UtilityElement or ArcGISFeature objects the UtilityNetwork creates or uses be associated with those existing FeatureTable and FeatureLayer. Usually used when instantiating a UtilityNetwork object from a web map.

      Parameters:
      url - the URL to the feature service
      map - An ArcGISMap that provides FeatureTables to be reused by the utility network
      Throws:
      IllegalArgumentException - if url is null or empty
      IllegalArgumentException - if the map is null
      Since:
      100.6.0

  • Method Details

    • getDefinition

      public UtilityNetworkDefinition getDefinition()
      Gets the definition of the utility network.

      This definition is null until the utility network is loaded.

      Returns:
      the definition of the UtilityNetwork, or null if none
      Since:
      100.6.0

    • getName

      public String getName()
      Gets the name of the utility network. This property is empty when UtilityNetwork is not retrieved from a Geodatabase.
      Returns:
      the name of the utility network
      Since:
      100.8.0

    • dirtyAreaTableProperty

      public ReadOnlyObjectProperty<ArcGISFeatureTable> dirtyAreaTableProperty()
      The dirty area table of the UtilityNetwork.

      A read-only table that can be used to query features that represent either:

      • a new or modified feature in the utility network that has not yet been validated in the network topology
      • an error that resulted from enabling or validating network topology or updating subnetworks

      A dirty area is created when modifications are made to feature geometry, asset group or asset type fields, network attribute fields, associations, or terminal configuration information.

      The dirty area table is null until the utility network is loaded or if the utility network does not support the network state.

      Returns:
      the dirtyAreaTable property
      Since:
      200.3.0
      See Also:

    • getDirtyAreaTable

      public ArcGISFeatureTable getDirtyAreaTable()
      Gets the value of the dirtyAreaTable property.
      Property description:
      The dirty area table of the UtilityNetwork.

      A read-only table that can be used to query features that represent either:

      • a new or modified feature in the utility network that has not yet been validated in the network topology
      • an error that resulted from enabling or validating network topology or updating subnetworks

      A dirty area is created when modifications are made to feature geometry, asset group or asset type fields, network attribute fields, associations, or terminal configuration information.

      The dirty area table is null until the utility network is loaded or if the utility network does not support the network state.

      Returns:
      the value of the dirtyAreaTable property
      Since:
      200.3.0
      See Also:

    • getGeodatabase

      public Geodatabase getGeodatabase()
      Gets the Geodatabase that contains this UtilityNetwork.

      The Geodatabase that contains this UtilityNetwork and is also used by the GeodatabaseFeatureTable in UtilityNetworkDefinition.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 a Geodatabase 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 this Geodatabase is closed will throw an ArcGISRuntimeException.

      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 interface RemoteResource
      Returns:
      the URL used to create the utility network
      Since:
      100.6.0

    • getLoadStatus

      public LoadStatus getLoadStatus()
      Gets the value of the loadStatus property.
      Specified by:
      getLoadStatus in interface Loadable
      Property description:
      Returns:
      the value of the loadStatus property
      See Also:

    • getLoadError

      public ArcGISRuntimeException getLoadError()
      Gets the value of the loadError property.
      Specified by:
      getLoadError in interface Loadable
      Property description:
      Returns:
      the value of the loadError property
      See Also:

    • 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 from LoadStatus.LOADING to LoadStatus.FAILED_TO_LOAD state. If the load operation was successfully cancelled, a CancellationException will be returned from Loadable.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 interface Loadable

    • 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 to LoadStatus.LOADING. A listener can be added via Loadable.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 calling Loadable.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) when loadAsync 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 or LoadStatus.FAILED_TO_LOAD state) when loadAsync 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 calling Loadable.cancelLoad().

      Specified by:
      loadAsync in interface Loadable

    • 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 interface Loadable

    • 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, add a listener to the Loadable.loadStatusProperty() instead.

      Specified by:
      addDoneLoadingListener in interface Loadable
      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 interface Loadable
      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 a LoadStatusChangedListener 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 interface Loadable
      Parameters:
      listener - the LoadStatusChangedListener to be added

    • removeLoadStatusChangedListener

      public boolean removeLoadStatusChangedListener(LoadStatusChangedListener listener)
      Description copied from interface: Loadable
      Removes a LoadStatusChangedListener from the loadable resource.
      Specified by:
      removeLoadStatusChangedListener in interface Loadable
      Parameters:
      listener - the LoadStatusChangedListener to be removed
      Returns:
      true if the listener was removed, otherwise false

    • loadStatusProperty

      public ReadOnlyObjectProperty<LoadStatus> loadStatusProperty()
      Description copied from interface: Loadable
      The load status.
      Specified by:
      loadStatusProperty in interface Loadable
      Returns:
      the loadStatus property
      See Also:

    • loadErrorProperty

      public ReadOnlyObjectProperty<ArcGISRuntimeException> loadErrorProperty()
      Description copied from interface: Loadable
      The load error.
      Specified by:
      loadErrorProperty in interface Loadable
      Returns:
      the loadError property
      See Also:

    • getCredential

      public Credential getCredential()
      Description copied from interface: RemoteResource
      Gets the Credential that is set on the network-enabled resource.

      Only applicable if the resource is secured.

      Specified by:
      getCredential in interface RemoteResource
      Returns:
      the Credential, or null if there is none

    • setCredential

      public void setCredential(Credential credential)
      Description copied from interface: RemoteResource
      Sets a Credential 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 interface RemoteResource
      Parameters:
      credential - the Credential to be used for authentication

    • getRequestConfiguration

      public RequestConfiguration getRequestConfiguration()
      Description copied from interface: RemoteResource
      Gets the RequestConfiguration used to modify the parameters of network requests made by this RemoteResource.
      Specified by:
      getRequestConfiguration in interface RemoteResource
      Returns:
      the RequestConfiguration used to modify network requests

    • setRequestConfiguration

      public void setRequestConfiguration(RequestConfiguration requestConfiguration)
      Description copied from interface: RemoteResource
      Sets the RequestConfiguration used to modify the parameters of network requests made by this RemoteResource. If not set, the global RequestConfiguration will be used (see RequestConfiguration.getGlobalRequestConfiguration()).
      Specified by:
      setRequestConfiguration in interface RemoteResource
      Parameters:
      requestConfiguration - the RequestConfiguration used to modify network requests

    • createElement

      public UtilityElement createElement(ArcGISFeature arcGISFeature)
      Creates a UtilityElement from an ArcGISFeature.

      If the feature's UtilityAssetType supports a UtilityTerminalConfiguration, a default UtilityTerminal 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 a UtilityElement from an ArcGISFeature and an optional UtilityTerminal.

      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's UtilityAssetType supports a UtilityTerminalConfiguration, a default UtilityTerminal will be assigned.

      Parameters:
      arcGISFeature - the Feature from which this UtilityElement is to be created
      terminal - 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 a UtilityElement from a UtilityAssetType and a global ID.

      If the UtilityAssetType supports a UtilityTerminalConfiguration, a default UtilityTerminal will be assigned.

      Parameters:
      assetType - the asset type of the Feature from which this UtilityElement is created
      globalId - 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 null
      IllegalArgumentException - if globalId is null
      Since:
      100.7.0

    • createElement

      public UtilityElement createElement(UtilityAssetType assetType, UUID globalId, UtilityTerminal terminal)
      Creates a UtilityElement from a UtilityAssetType, a global ID and an optional UtilityTerminal.

      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's UtilityAssetType supports a UtilityTerminalConfiguration, a default UtilityTerminal will be assigned.

      Parameters:
      assetType - the asset type of the Feature from which this UtilityElement is created
      globalId - the global ID of the Feature from which this UtilityElement is to be created
      terminal - the terminal for a junction feature
      Returns:
      the UtilityElement created from the given asset type, global id and terminal
      Throws:
      IllegalArgumentException - if assetType is null
      IllegalArgumentException - if globalId is null
      Since:
      100.6.0

    • traceAsync

      public ListenableFuture<List<UtilityTraceResult>> traceAsync(UtilityTraceParameters traceParameters)
      Begins a trace with the supplied UtilityTraceParameters.

      The result is an unmodifiable list of UtilityTraceResult objects containing UtilityElement if the result type specified by UtilityTraceParameters.getResultTypes() is UtilityTraceResult.Type.ELEMENTS.

      If the value returned by UtilityTraceParameters.getTraceType() is a subnetwork-based trace, it must have a UtilityDomainNetwork set in the UtilityTraceConfiguration returned from UtilityTraceParameters.getTraceConfiguration().

      Parameters:
      traceParameters - the object that holds all necessary parameters to run a trace
      Returns:
      a list of UtilityTraceResult objects when the trace is finished
      Throws:
      IllegalArgumentException - if traceParameters is null
      Since:
      100.6.0

    • validateNetworkTopology

      public UtilityNetworkValidationJob validateNetworkTopology(Envelope extent)
      Returns a job that when started will validate the utility network topology within the provided extent.

      The geoprocessing execution type is GeoprocessingParameters.ExecutionType.SYNCHRONOUS_EXECUTE.

      The job that is returned is dormant and needs to be explicitly started.

      When working with an enterprise geodatabase, only a single session can run the validate operation at a time in the default version.

      See Enable and validate network topology errors for more information on validation errors.

      Parameters:
      extent - the extent of the area to be validated
      Returns:
      a UtilityNetworkValidationJob to validate network topology
      Throws:
      NullPointerException - if extent is null
      Since:
      200.3.0
      See Also:

    • validateNetworkTopology

      public UtilityNetworkValidationJob validateNetworkTopology(Envelope extent, GeoprocessingParameters.ExecutionType geoprocessingExecutionType)
      Returns a job that when started will validate the utility network topology within the provided extent.

      The preferred job execution type is ExecutionType.SYNCHRONOUS_EXECUTE because it is faster to start up. For larger jobs, ExecutionType.SYNCHRONOUS_EXECUTE can lead to timeouts, at which point ExecutionType.ASYNCHRONOUS_SUBMIT should be used.

      The job that is returned is dormant and needs to be explicitly started.

      When working with an enterprise geodatabase, only a single session can run the validate operation at a time in the default version.

      See Enable and validate network topology errors for more information on validation errors.

      Parameters:
      extent - the extent of the area to be validated
      geoprocessingExecutionType - an GeoprocessingParameters.ExecutionType indicating the job execution type. The value passed in must be either ExecutionType.ASYNCHRONOUS_SUBMIT or ExecutionType.SYNCHRONOUS_EXECUTE.
      Returns:
      a UtilityNetworkValidationJob to validate network topology
      Throws:
      NullPointerException - if extent is null
      NullPointerException - if geoprocessingExecutionType is null
      Since:
      200.3.0
      See Also:

    • 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 all UtilityAssociation objects (with their geometry) present in the geodatabase for a given Envelope.

      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 - the Envelope 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 all UtilityAssociation objects (with their geometry) of type UtilityAssociationType present in the geodatabase for a given Envelope.

      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 - the Envelope that defines the area for which to return associations
      type - the UtilityAssociationType 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 all UtilityAssociation objects present in the geodatabase for a given UtilityElement.

      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 - the UtilityElement 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 all UtilityAssociation objects of type UtilityAssociationType present in the geodatabase for a given UtilityElement.

      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 - the UtilityElement whose associations are to be returned
      type - the UtilityAssociationType 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 null
      IllegalArgumentException - if type is null
      Since:
      100.7.0

    • stateAsync

      public ListenableFuture<UtilityNetworkState> stateAsync()
      Returns a UtilityNetworkState that represents the current state of the utility network.

      This state is unavailable if the utility network does not support the network state.

      When the task executes it can fail with an exception if:

      Returns:
      a ListenableFuture that returns a UtilityNetworkState
      Since:
      200.3.0
      See Also:

    • queryNamedTraceConfigurationsAsync

      public ListenableFuture<List<UtilityNamedTraceConfiguration>> queryNamedTraceConfigurationsAsync(UtilityNamedTraceConfigurationQueryParameters queryParameters)
      Returns a list of UtilityNamedTraceConfiguration from the utility network.
      Parameters:
      queryParameters - optional query parameter to filter the results, may be null
      Returns:
      a list of UtilityNamedTraceConfiguration objects from the utility network
      Since:
      100.11.0

    • getServiceGeodatabase

      public ServiceGeodatabase getServiceGeodatabase()
      Gets the ServiceGeodatabase of the UtilityNetwork.

      The ServiceGeodatabase is used by the ServiceFeatureTable in UtilityNetworkDefinition.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 in FeatureServiceSessionType.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 an ArcGISRuntimeException.

      Returns:
      the ServiceGeodatabase of the UtilityNetwork
      Since:
      100.10.0