Class UtilityTraceConfiguration


  • public final class UtilityTraceConfiguration
    extends java.lang.Object
    The set of utility network parameters that define elements of a trace or of a subnetwork. UtilityTraceConfiguration is set in the UtilityTraceParameters.
    Since:
    100.7.0
    • Constructor Detail

      • UtilityTraceConfiguration

        public UtilityTraceConfiguration()
        Creates a new instance of UtilityTraceConfiguration.
        Since:
        100.7.0
    • Method Detail

      • setDomainNetwork

        public void setDomainNetwork​(UtilityDomainNetwork utilityDomainNetwork)
        Sets the utility domain network from which to start the trace.

        The domain network property is required and only used with subnetwork-based traces UtilityTraceType.SUBNETWORK, UtilityTraceType.UPSTREAM and so on.

        Parameters:
        utilityDomainNetwork - the utility domain network or null if none
        Since:
        100.7.0
      • getFilter

        public UtilityTraceFilter getFilter()
        Gets the criteria that define the dynamic barriers for the trace.
        Returns:
        the utility trace filter or null if none
        Since:
        100.8.0
      • setFilter

        public void setFilter​(UtilityTraceFilter utilityTraceFilter)
        Sets the criteria that define the dynamic barriers for the trace.
        Parameters:
        utilityTraceFilter - the utility trace filter or null if none
        Since:
        100.8.0
      • isIgnoreBarriersAtStartingPoints

        public boolean isIgnoreBarriersAtStartingPoints()
        Indicates whether to ignore barriers at starting points.

        The default is false. One example of how this can be used is with an upstream protective device trace. The first call to the trace will return the first upstream device that meets the protective device criteria. To find the next device upstream, you would set a starting point on the device returned by the first trace. With isIgnoreBarriersAtStartingPoints() set to false, this second trace would immediately stop at the starting point, since it meets the trace termination criteria. Setting this option to true will allow the trace to ignore the starting point, and continue to the subsequent device upstream.

        Returns:
        whether the barriers at starting points are ignored
        Since:
        100.7.0
      • setIgnoreBarriersAtStartingPoints

        public void setIgnoreBarriersAtStartingPoints​(boolean isIgnoreBarriersAtStartingPoints)
        Sets whether to ignore barriers at starting points.

        The default is false. One example of how this can be used is with an upstream protective device trace. The first call to the trace will return the first upstream device that meets the protective device criteria. To find the next device upstream, you would set a starting point on the device returned by the first trace. With isIgnoreBarriersAtStartingPoints() set to false, this second trace would immediately stop at the starting point, since it meets the trace termination criteria. Setting this option to true will allow the trace to ignore the starting point, and continue to the subsequent device upstream.

        Parameters:
        isIgnoreBarriersAtStartingPoints - true for the trace to ignore barriers at starting points, false otherwise
        Since:
        100.7.0
      • isIncludeBarriers

        public boolean isIncludeBarriers()
        Indicates whether to include barriers in the trace results or subnetwork.

        The default is true.

        Returns:
        whether to include barriers in the trace results or subnetwork
        Since:
        100.7.0
      • setIncludeBarriers

        public void setIncludeBarriers​(boolean includeBarriers)
        Sets whether to include barriers in the trace results or subnetwork.
        Parameters:
        includeBarriers - true barriers in the trace results or subnetwork will be included, false otherwise
        Since:
        100.7.0
      • isIncludeContainers

        public boolean isIncludeContainers()
        Indicates whether to include containment features in the trace results or subnetwork.

        The default is false.

        Returns:
        whether to include containment features in the trace results or subnetwork
        Since:
        100.7.0
      • setIncludeContainers

        public void setIncludeContainers​(boolean includeContainers)
        Sets whether to include containment features in the trace results or subnetwork.
        Parameters:
        includeContainers - true containment features in the trace results or subnetwork will be included, false otherwise
        Since:
        100.7.0
      • isIncludeContent

        public boolean isIncludeContent()
        Indicates whether to include content in the trace results or subnetwork.

        The default is false.

        Returns:
        whether to include content in the trace results or subnetwork
        Since:
        100.7.0
      • setIncludeContent

        public void setIncludeContent​(boolean includeContent)
        Sets whether to include content in the trace results or subnetwork.
        Parameters:
        includeContent - true content in the trace results or subnetwork will be included, false otherwise
        Since:
        100.7.0
      • isIncludeIsolatedFeatures

        public boolean isIncludeIsolatedFeatures()
        Indicates whether to include isolated features in the trace results when used in conjunction with UtilityTraceType.ISOLATION.

        The default is false.

        Returns:
        Whether to include isolated features in the trace results when used in conjunction with an isolation trace
        Since:
        100.8.0
      • setIncludeIsolatedFeatures

        public void setIncludeIsolatedFeatures​(boolean includeIsolatedFeatures)
        Sets whether to include isolated features in the trace results when used in conjunction with UtilityTraceType.ISOLATION.
        Parameters:
        includeIsolatedFeatures - true if isolated features in the trace results will be included when used in conjunction with an isolation trace, false otherwise
        Since:
        100.8.0
      • isIncludeStructures

        public boolean isIncludeStructures()
        Indicates whether to include structure features in the trace results or subnetwork.

        The default is false.

        Returns:
        whether to include structure features in the trace results or subnetwork
        Since:
        100.7.0
      • setIncludeStructures

        public void setIncludeStructures​(boolean includeStructures)
        Sets whether to include structure features in the trace results or subnetwork.
        Parameters:
        includeStructures - true structure features in the trace results or subnetwork will be included, false otherwise.
        Since:
        100.7.0
      • isValidateConsistency

        public boolean isValidateConsistency()
        Indicates whether to validate network consistency as part of the trace operation.

        If set to true, trace operations will fail if dirty areas are encountered during the trace. The default is true.

        Returns:
        whether to validate network consistency as part of the trace operation
        Since:
        100.7.0
      • setValidateConsistency

        public void setValidateConsistency​(boolean validateConsistency)
        Sets whether to validate network consistency as part of the trace operation.

        If set to true, trace operations will fail if dirty areas are encountered during the trace. The default is true.

        Parameters:
        validateConsistency - true to validate network consistency as part of the trace operation, false otherwise
        Since:
        100.7.0
      • getSourceTier

        public UtilityTier getSourceTier()
        Gets the utility tier that is used as the start of the trace.

        This property is only used with subnetwork-based traces (for example subnetwork upstream). If getDomainNetwork() represents a partitioned network, this property is optional. If not null, the trace routines will perform an additional check to validate that the starting points and barriers belong to this tier. If getDomainNetwork() represents a hierarchical network, this property is required. Since rows in hierarchical networks can belong to multiple tiers, this property tells the subnetwork tracer which tier to use for tracing.

        Returns:
        the source utility tier or null if no source tier is set
        Since:
        100.7.0
      • setSourceTier

        public void setSourceTier​(UtilityTier utilityTier)
        Sets the utility tier to be used as the start of the trace.

        This property is only used with subnetwork-based traces (for example subnetwork upstream). If getDomainNetwork() represents a partitioned network, this property is optional. If not null, the trace routines will perform an additional check to validate that the starting points and barriers belong to this tier. If getDomainNetwork() represents a hierarchical network, this property is required. Since rows in hierarchical networks can belong to multiple tiers, this property tells the subnetwork tracer which tier to use for tracing.

        Parameters:
        utilityTier - the source utility tier to be used as the start of the trace or null if none
        Since:
        100.7.0
      • getTargetTier

        public UtilityTier getTargetTier()
        Gets the utility tier that is used to constrain the tiers returned by the upstream and downstream traces.

        This property is optional. If null, the upstream and downstream traces will stop in the current tier. If a target tier is specified, the trace will continue upstream or downstream into the specified tier (inclusive).

        Returns:
        the target utility tier or null if no target tier is set
        Since:
        100.7.0
      • setTargetTier

        public void setTargetTier​(UtilityTier utilityTier)
        Sets the utility tier that is used to constrain the tiers returned by the upstream and downstream traces.

        This property is optional. If null, the upstream and downstream traces will stop in the current tier. If a target tier is specified, the trace will continue upstream or downstream into the specified tier (inclusive).

        Parameters:
        utilityTier - the target utility tier to be used to constrain the tiers or null if none
        Since:
        100.7.0
      • getTraversability

        public UtilityTraversability getTraversability()
        Gets the traversability conditions for the trace.
        Returns:
        the traversability conditions for the trace or null if none
        Since:
        100.7.0
      • setTraversability

        public void setTraversability​(UtilityTraversability traversability)
        Sets the traversability conditions for the trace.
        Parameters:
        traversability - the traversability conditions for the trace or null if none
        Since:
        100.7.0
      • getPropagators

        public java.util.List<UtilityPropagator> getPropagators()
        Gets a mutable list of UtilityPropagator objects to execute while performing the trace. Initially it is empty.

        Propagator objects allow a subset of UtilityNetworkAttribute values to propagate through a network while executing a trace. For example, in phase propagation, open devices along the network will restrict some phases from continuing along the trace. Propagators only apply to subnetwork-based traces (UtilityTraceType.UPSTREAM, UtilityTraceType.DOWNSTREAM, and so on).

        Returns:
        a mutable list of UtilityPropagators to execute while performing the trace
        Since:
        100.7.0
      • getOutputAssetTypes

        public java.util.List<UtilityAssetType> getOutputAssetTypes()
        Gets a mutable list of UtilityAssetType objects which specifies what to include in the trace results.

        Only elements that belong to this UtilityAssetType are included in the trace result. This property is independent of asset types set using getFilter(). This is applied after all other tracing calculations, including traversal, filters, and function calculation. If this is empty and the output condition is null, all elements are returned. Otherwise, elements which match either of these criteria are returned.

        Returns:
        a mutable list of UtilityAssetTypes which specifies what to include in the trace results
        Since:
        100.9.0
      • getShortestPathNetworkAttribute

        public UtilityNetworkAttribute getShortestPathNetworkAttribute()
        Gets the the UtilityNetworkAttribute used to calculate the shortest path, or null if none.

        The shortest path may depend on some other numeric weight, such as cost or difficulty, rather than the shortest distance calculated from shape length.

        Returns:
        the UtilityNetworkAttribute used to calculate the shortest path, or null if none
        Since:
        100.9.0
      • setShortestPathNetworkAttribute

        public void setShortestPathNetworkAttribute​(UtilityNetworkAttribute shortestPathNetworkAttribute)
        Sets the the UtilityNetworkAttribute used to calculate the shortest path, or null if none.

        The shortest path may depend on some other numeric weight, such as cost or difficulty, rather than the shortest distance calculated from shape length.

        Parameters:
        shortestPathNetworkAttribute - the UtilityNetworkAttribute used to calculate the shortest path, can be null
        Since:
        100.9.0