Class UtilityTraceConfiguration
UtilityTraceConfiguration
is set in the UtilityTraceParameters
.- Since:
- 100.7.0
-
Property Summary
TypePropertyDescriptionTrue to allow tracing across network features with indeterminate flow or false to stop the traversal when indeterminate flow is encountered.True to include containment associations up to and including the first spatial container or false to include all containment associations.True to fail trace operations if non-spatial objects are encountered without the necessary containment, attachment, or connectivity association to a spatial object, or false to allow tracing of those non-spatial objects. -
Constructor Summary
ConstructorDescriptionCreates a new instance of UtilityTraceConfiguration. -
Method Summary
Modifier and TypeMethodDescriptionTrue to allow tracing across network features with indeterminate flow or false to stop the traversal when indeterminate flow is encountered.Gets the utility domain network from which to start the trace.Gets the criteria that define the dynamic barriers for the trace.Gets a mutable list ofUtilityTraceFunction
objects to compute while performing the trace.Gets a mutable list ofUtilityAssetType
objects which specifies what to include in the trace results.Gets a condition object which specifies what to include in the trace results, or null if none.Gets a mutable list ofUtilityPropagator
objects to execute while performing the trace.Gets the the UtilityNetworkAttribute used to calculate the shortest path, or null if none.Gets the utility tier that is used as the start of the trace.Gets the utility tier that is used to constrain the tiers returned by the upstream and downstream traces.Gets the traversability conditions for the trace.True to include containment associations up to and including the first spatial container or false to include all containment associations.boolean
Gets the value of theallowIndeterminateFlow
property.boolean
Indicates whether to ignore barriers at starting points.boolean
Indicates whether to include barriers in the trace results or subnetwork.boolean
Indicates whether to include containment features in the trace results or subnetwork.boolean
Indicates whether to include content in the trace results or subnetwork.boolean
Indicates whether to include isolated features in the trace results when used in conjunction withUtilityTraceType.ISOLATION
.boolean
Indicates whether to include structure features in the trace results or subnetwork.boolean
Gets the value of theincludeUpToFirstSpatialContainer
property.boolean
Indicates whether to validate network consistency as part of the trace operation.boolean
Gets the value of thevalidateLocatability
property.void
setAllowIndeterminateFlow
(boolean allowIndeterminateFlow) Sets the value of theallowIndeterminateFlow
property.void
setDomainNetwork
(UtilityDomainNetwork utilityDomainNetwork) Sets the utility domain network from which to start the trace.void
setFilter
(UtilityTraceFilter utilityTraceFilter) Sets the criteria that define the dynamic barriers for the trace.void
setIgnoreBarriersAtStartingPoints
(boolean isIgnoreBarriersAtStartingPoints) Sets whether to ignore barriers at starting points.void
setIncludeBarriers
(boolean includeBarriers) Sets whether to include barriers in the trace results or subnetwork.void
setIncludeContainers
(boolean includeContainers) Sets whether to include containment features in the trace results or subnetwork.void
setIncludeContent
(boolean includeContent) Sets whether to include content in the trace results or subnetwork.void
setIncludeIsolatedFeatures
(boolean includeIsolatedFeatures) Sets whether to include isolated features in the trace results when used in conjunction withUtilityTraceType.ISOLATION
.void
setIncludeStructures
(boolean includeStructures) Sets whether to include structure features in the trace results or subnetwork.void
setIncludeUpToFirstSpatialContainer
(boolean includeUpToFirstSpatialContainer) Sets the value of theincludeUpToFirstSpatialContainer
property.void
setOutputCondition
(UtilityTraceCondition utilityTraceCondition) Sets a condition object which specifies what to include in the trace results, or null if none.void
setShortestPathNetworkAttribute
(UtilityNetworkAttribute shortestPathNetworkAttribute) Sets the the UtilityNetworkAttribute used to calculate the shortest path, or null if none.void
setSourceTier
(UtilityTier utilityTier) Sets the utility tier to be used as the start of the trace.void
setTargetTier
(UtilityTier utilityTier) Sets the utility tier that is used to constrain the tiers returned by the upstream and downstream traces.void
setTraversability
(UtilityTraversability traversability) Sets the traversability conditions for the trace.void
setValidateConsistency
(boolean validateConsistency) Sets whether to validate network consistency as part of the trace operation.void
setValidateLocatability
(boolean validateLocatability) Sets the value of thevalidateLocatability
property.True to fail trace operations if non-spatial objects are encountered without the necessary containment, attachment, or connectivity association to a spatial object, or false to allow tracing of those non-spatial objects.
-
Property Details
-
allowIndeterminateFlow
True to allow tracing across network features with indeterminate flow or false to stop the traversal when indeterminate flow is encountered.Indeterminate flow can occur when there is a loop in the network where traversal in either direction could be used to find the subnetwork controller (both upstream and downstream at the same time, in other words). This property is useful for upstream, downstream, or isolation traces where flow direction for the subnetwork is determined.
This option is only applicable with Utility Network versions 5 or higher.
The default is true.
- Since:
- 200.1.0
- See Also:
-
includeUpToFirstSpatialContainer
True to include containment associations up to and including the first spatial container or false to include all containment associations.This property depends on the
isIncludeContainers()
property and is ignored if it's false. If no spatial containers are encountered but non-spatial containers are present for a given network element, all non-spatial containers are included in the results. This is typically used with telecommunications networks with multiple levels of containment with non-spatial objects (for example, splice points within a splice tray within a splice container).The default is false.
- Since:
- 200.1.0
- See Also:
-
validateLocatability
True to fail trace operations if non-spatial objects are encountered without the necessary containment, attachment, or connectivity association to a spatial object, or false to allow tracing of those non-spatial objects.Locatability is determined by whether a non-spatial object has implied geometry. Geometry is implied for non-spatial objects if they are associated via containment (possibly multiple levels) with spatial features. This is typically used with telecommunications networks with many non-spatial objects. For example, if a splice tray (non-spatial junction object) is contained within a splice container (assembly feature), then it would be considered locatable.
This property is only applicable for Utility Network versions 4 or later.
The default is false.
- Since:
- 200.1.0
- See Also:
-
-
Constructor Details
-
UtilityTraceConfiguration
public UtilityTraceConfiguration()Creates a new instance of UtilityTraceConfiguration.- Since:
- 100.7.0
-
-
Method Details
-
getDomainNetwork
Gets 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.- Returns:
- the domain network, or null if none
- Since:
- 100.7.0
-
setDomainNetwork
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
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
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
-
getFunctions
Gets a mutable list ofUtilityTraceFunction
objects to compute while performing the trace. EachUtilityTraceFunction
returns aUtilityTraceFunctionOutput
in theUtilityFunctionTraceResult
.- Returns:
- a collection of UtilityTraceFunction objects to compute while performing the trace
- Since:
- 100.9.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 withUtilityTraceType.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 withUtilityTraceType.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
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. IfgetDomainNetwork()
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
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. IfgetDomainNetwork()
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
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
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
Gets the traversability conditions for the trace.- Returns:
- the traversability conditions for the trace or null if none
- Since:
- 100.7.0
-
setTraversability
Sets the traversability conditions for the trace.- Parameters:
traversability
- the traversability conditions for the trace or null if none- Since:
- 100.7.0
-
getPropagators
Gets a mutable list ofUtilityPropagator
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
Gets a mutable list ofUtilityAssetType
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 usinggetFilter()
. 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
-
getOutputCondition
Gets a condition object which specifies what to include in the trace results, or null if none.Only elements that satisfy this
UtilityTraceCondition
are included in the trace result. This condition may perform comparisons againstUtilityNetworkAttributeComparison
andUtilityCategoryComparison
, or both (UtilityTraceAndCondition
,UtilityTraceOrCondition
). This property is independent of barriers in the configuration'sUtilityTraversability
orUtilityTraceFilter
. This is applied after all other tracing calculations, including traversal, filters, and function calculation. If this is null and the list of outputUtilityAssetType
is empty, all elements are returned. Otherwise, elements which match either of these criteria are returned.- Returns:
- a condition object which specifies what to include in the trace results, or null if none
- Since:
- 100.9.0
-
setOutputCondition
Sets a condition object which specifies what to include in the trace results, or null if none.Only elements that satisfy this
UtilityTraceCondition
are included in the trace result. This condition may perform comparisons againstUtilityNetworkAttributeComparison
andUtilityCategoryComparison
, or both (UtilityTraceAndCondition
,UtilityTraceOrCondition
). This property is independent of barriers in the configuration'sUtilityTraversability
orUtilityTraceFilter
. This is applied after all other tracing calculations, including traversal, filters, and function calculation. If this is null and the list of outputUtilityAssetType
is empty, all elements are returned. Otherwise, elements which match either of these criteria are returned.- Parameters:
utilityTraceCondition
- a condition object which specifies what to include in the trace results, can be null- Since:
- 100.9.0
-
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
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
-
allowIndeterminateFlowProperty
True to allow tracing across network features with indeterminate flow or false to stop the traversal when indeterminate flow is encountered.Indeterminate flow can occur when there is a loop in the network where traversal in either direction could be used to find the subnetwork controller (both upstream and downstream at the same time, in other words). This property is useful for upstream, downstream, or isolation traces where flow direction for the subnetwork is determined.
This option is only applicable with Utility Network versions 5 or higher.
The default is true.
- Returns:
- the
allowIndeterminateFlow
property - Since:
- 200.1.0
- See Also:
-
isAllowIndeterminateFlow
public boolean isAllowIndeterminateFlow()Gets the value of theallowIndeterminateFlow
property.- Property description:
- True to allow tracing across network features with indeterminate flow or false to stop the traversal when
indeterminate flow is encountered.
Indeterminate flow can occur when there is a loop in the network where traversal in either direction could be used to find the subnetwork controller (both upstream and downstream at the same time, in other words). This property is useful for upstream, downstream, or isolation traces where flow direction for the subnetwork is determined.
This option is only applicable with Utility Network versions 5 or higher.
The default is true.
- Returns:
- the value of the
allowIndeterminateFlow
property - Since:
- 200.1.0
- See Also:
-
setAllowIndeterminateFlow
public void setAllowIndeterminateFlow(boolean allowIndeterminateFlow) Sets the value of theallowIndeterminateFlow
property.- Property description:
- True to allow tracing across network features with indeterminate flow or false to stop the traversal when
indeterminate flow is encountered.
Indeterminate flow can occur when there is a loop in the network where traversal in either direction could be used to find the subnetwork controller (both upstream and downstream at the same time, in other words). This property is useful for upstream, downstream, or isolation traces where flow direction for the subnetwork is determined.
This option is only applicable with Utility Network versions 5 or higher.
The default is true.
- Parameters:
allowIndeterminateFlow
- the value for theallowIndeterminateFlow
property- Since:
- 200.1.0
- See Also:
-
includeUpToFirstSpatialContainerProperty
True to include containment associations up to and including the first spatial container or false to include all containment associations.This property depends on the
isIncludeContainers()
property and is ignored if it's false. If no spatial containers are encountered but non-spatial containers are present for a given network element, all non-spatial containers are included in the results. This is typically used with telecommunications networks with multiple levels of containment with non-spatial objects (for example, splice points within a splice tray within a splice container).The default is false.
- Returns:
- the
includeUpToFirstSpatialContainer
property - Since:
- 200.1.0
- See Also:
-
isIncludeUpToFirstSpatialContainer
public boolean isIncludeUpToFirstSpatialContainer()Gets the value of theincludeUpToFirstSpatialContainer
property.- Property description:
- True to include containment associations up to and including the first spatial container or false to include all
containment associations.
This property depends on the
isIncludeContainers()
property and is ignored if it's false. If no spatial containers are encountered but non-spatial containers are present for a given network element, all non-spatial containers are included in the results. This is typically used with telecommunications networks with multiple levels of containment with non-spatial objects (for example, splice points within a splice tray within a splice container).The default is false.
- Returns:
- the value of the
includeUpToFirstSpatialContainer
property - Since:
- 200.1.0
- See Also:
-
setIncludeUpToFirstSpatialContainer
public void setIncludeUpToFirstSpatialContainer(boolean includeUpToFirstSpatialContainer) Sets the value of theincludeUpToFirstSpatialContainer
property.- Property description:
- True to include containment associations up to and including the first spatial container or false to include all
containment associations.
This property depends on the
isIncludeContainers()
property and is ignored if it's false. If no spatial containers are encountered but non-spatial containers are present for a given network element, all non-spatial containers are included in the results. This is typically used with telecommunications networks with multiple levels of containment with non-spatial objects (for example, splice points within a splice tray within a splice container).The default is false.
- Parameters:
includeUpToFirstSpatialContainer
- the value for theincludeUpToFirstSpatialContainer
property- Since:
- 200.1.0
- See Also:
-
validateLocatabilityProperty
True to fail trace operations if non-spatial objects are encountered without the necessary containment, attachment, or connectivity association to a spatial object, or false to allow tracing of those non-spatial objects.Locatability is determined by whether a non-spatial object has implied geometry. Geometry is implied for non-spatial objects if they are associated via containment (possibly multiple levels) with spatial features. This is typically used with telecommunications networks with many non-spatial objects. For example, if a splice tray (non-spatial junction object) is contained within a splice container (assembly feature), then it would be considered locatable.
This property is only applicable for Utility Network versions 4 or later.
The default is false.
- Returns:
- the
validateLocatability
property - Since:
- 200.1.0
- See Also:
-
isValidateLocatability
public boolean isValidateLocatability()Gets the value of thevalidateLocatability
property.- Property description:
- True to fail trace operations if non-spatial objects are encountered without the necessary containment, attachment,
or connectivity association to a spatial object, or false to allow tracing of those non-spatial objects.
Locatability is determined by whether a non-spatial object has implied geometry. Geometry is implied for non-spatial objects if they are associated via containment (possibly multiple levels) with spatial features. This is typically used with telecommunications networks with many non-spatial objects. For example, if a splice tray (non-spatial junction object) is contained within a splice container (assembly feature), then it would be considered locatable.
This property is only applicable for Utility Network versions 4 or later.
The default is false.
- Returns:
- the value of the
validateLocatability
property - Since:
- 200.1.0
- See Also:
-
setValidateLocatability
public void setValidateLocatability(boolean validateLocatability) Sets the value of thevalidateLocatability
property.- Property description:
- True to fail trace operations if non-spatial objects are encountered without the necessary containment, attachment,
or connectivity association to a spatial object, or false to allow tracing of those non-spatial objects.
Locatability is determined by whether a non-spatial object has implied geometry. Geometry is implied for non-spatial objects if they are associated via containment (possibly multiple levels) with spatial features. This is typically used with telecommunications networks with many non-spatial objects. For example, if a splice tray (non-spatial junction object) is contained within a splice container (assembly feature), then it would be considered locatable.
This property is only applicable for Utility Network versions 4 or later.
The default is false.
- Parameters:
validateLocatability
- the value for thevalidateLocatability
property- Since:
- 200.1.0
- See Also:
-