Package com.esri.arcgisruntime.utilitynetworks

Class UtilityNetwork

    • Constructor Detail

      • UtilityNetwork

        public UtilityNetwork​(java.lang.String url)
        Creates a utility network from the provided URL to the feature service.
        Parameters:
        url - the URL to the feature service
        Throws:
        java.lang.IllegalArgumentException - if url is null or empty
        Since:
        100.6.0

      • UtilityNetwork

        public UtilityNetwork​(java.lang.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:
        java.lang.IllegalArgumentException - if url is null or empty
        java.lang.IllegalArgumentException - 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 java.lang.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

      • 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 java.lang.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()
        Description copied from interface: Loadable
        Returns the LoadStatus of the loadable resource.
        Specified by:
        getLoadStatus in interface Loadable
        Returns:
        the LoadStatus of the loadable resource

      • 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​(java.lang.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 interface Loadable
        Parameters:
        listener - a Runnable that is invoked upon completion of the load operation

      • removeDoneLoadingListener

        public boolean removeDoneLoadingListener​(java.lang.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

      • 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

      • 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:
        java.lang.IllegalArgumentException - if arcGISFeature is null
        Since:
        100.6.0

      • createElement

        public UtilityElement createElement​(UtilityAssetType assetType,
                                    java.util.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:
        java.lang.IllegalArgumentException - if assetType is null
        java.lang.IllegalArgumentException - if globalId is null
        Since:
        100.7.0

      • createElement

        public UtilityElement createElement​(UtilityAssetType assetType,
                                    java.util.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:
        java.lang.IllegalArgumentException - if assetType is null
        java.lang.IllegalArgumentException - if globalId is null
        Since:
        100.6.0

      • fetchFeaturesForElementsAsync

        public ListenableFuture<java.util.List<ArcGISFeature>> fetchFeaturesForElementsAsync​(java.lang.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:
        java.lang.IllegalArgumentException - if utilityElements is null or empty
        Since:
        100.6.0

      • getAssociationsAsync

        public ListenableFuture<java.util.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:
        java.lang.IllegalArgumentException - if extent is null
        Since:
        100.8.0

      • getAssociationsAsync

        public ListenableFuture<java.util.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:
        java.lang.IllegalArgumentException - if extent or type is null
        Since:
        100.8.0

      • getAssociationsAsync

        public ListenableFuture<java.util.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:
        java.lang.IllegalArgumentException - if element is null
        Since:
        100.7.0

      • getAssociationsAsync

        public ListenableFuture<java.util.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:
        java.lang.IllegalArgumentException - if element is null
        java.lang.IllegalArgumentException - if type is null
        Since:
        100.7.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