com.esri.arcgis.networkanalyst
Interface INALocator3

All Superinterfaces:

INALocator, INALocator2, Serializable

All Known Implementing Classes:

NALocator

public interface INALocator3
extends INALocator2, Serializable

Provides access to properties that apply to all network locators.

Remarks

The INALocator3 interface provides methods to specify settings and make calls to associated NALocatorAgents.

The interface also provides methods that allow the NALocator to automatically expand the snap tolerance when loading network locations. The tolerance begins at the SnapTolerance and doubles each time until either a network location is found or the MaxSnapTolerance value is reached.

Generally, the NALocator should be retrieved from an NAContext. However, if you do create an NALocator, or have added a new locator agent, then, before querying the NALocator, Bind should be called on the NALocator to set up the locator agents and associate it with the NetworkDataset.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Method Summary

void	cacheRestrictedElements(INAContext context) The locator will examine the NAContext and its associated NASolver to build a cache of network elements that cannot be located on due to restrictions, barriers, etc.
boolean	isExcludeRestrictedElements() Indicates whether to exclude restricted portions of the network when locating points.
void	queryLocationByPointEx(IPoint point, int curbApproach, INALocation[] location, IPoint[] outPoint, double[] distanceFromPoint) Use the locator agents to find a network location from a point and curb approach.
void	queryLocationByRowEx(IRow row, int curbApproach, INALocation[] location, double[] distanceFromRow) Use the locator agents to find a network location from a row and curb approach.
void	queryLocationRangesByGeometry(IGeometry geometry, INALocationRanges[] locationRanges) Use the locator agents to find network location ranges from a geometry.
void	queryLocationRangesByRow(IRow row, INALocationRanges[] locationRanges) Use the locator agents to find a network location ranges from a row.
void	setExcludeRestrictedElements(boolean excludeRestricted) Indicates whether to exclude restricted portions of the network when locating points.

Methods inherited from interface com.esri.arcgis.networkanalyst.INALocator2

geocodeLocation, getMaxSnapTolerance, queryOffsetPoint, reverseGeocodeLocation, setMaxSnapTolerance

Methods inherited from interface com.esri.arcgis.networkanalyst.INALocator

addLocatorAgent, bind, createDefault, getLocatorAgent, getLocatorAgentCount, getNetworkDataset, getOutputSpatialReference, getSnapTolerance, getSnapToleranceUnits, isFindClosestAmongAllAgents, queryLocationByPoint, queryLocationByRow, queryPoint, removeLocatorAgent, setFindClosestAmongAllAgents, setOutputSpatialReferenceByRef, setSnapTolerance, setSnapToleranceUnits

Method Detail

queryLocationRangesByGeometry

void queryLocationRangesByGeometry(IGeometry geometry,
                                   INALocationRanges[] locationRanges)
                                   throws IOException,
                                          AutomationException

Use the locator agents to find network location ranges from a geometry.

Remarks

Using the input geometry, this method calls QueryLocationRangesByGeometry on each of its associated NALocatorAgent classes. Via these associated NALocatorAgent classes, QueryLocationRangesByGeometry determines the set of junctions and edge ranges that intersect the input geometry and returns this information by populating the referenced INALocationRanges parameter.

Generally, the NALocator used for this method should be retrieved from a NAContext. However, if you do create a NALocator, or have added a new locator agent, then, before querying the NALocator, Bind should be called on the NALocator to set up the locator agents and associate it with the NetworkDataset.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)

locationRanges - A reference to a com.esri.arcgis.networkanalyst.INALocationRanges (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

queryLocationRangesByRow

void queryLocationRangesByRow(IRow row,
                              INALocationRanges[] locationRanges)
                              throws IOException,
                                     AutomationException

Use the locator agents to find a network location ranges from a row.

Remarks

Using the inbound Row object, the method calls QueryLocationRangesByRow on each of its associated NALocatorAgent classes.

Generally, the NALocator used for this method should be retrieved from a NAContext. However, if you do create a NALocator, or have added a new locator agent, then, before querying the NALocator, Bind should be called on the NALocator to set up the locator agents and associate it with the NetworkDataset.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

row - A reference to a com.esri.arcgis.geodatabase.IRow (in)

locationRanges - A reference to a com.esri.arcgis.networkanalyst.INALocationRanges (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setExcludeRestrictedElements

void setExcludeRestrictedElements(boolean excludeRestricted)
                                  throws IOException,
                                         AutomationException

Indicates whether to exclude restricted portions of the network when locating points.

Remarks

When ExcludeRestrictedElements is set to true, the INALocator location queries will not return network locations that fall on restricted network elements. The reason a network element could be restricted due to a point, polyline or polygon barrier, restriction network attributes, and/or elements with a negative impedance value.

If you set ExcludeRestrictedElements to true, then before calling any of the query location methods, be sure to call INALocator3::CacheRestrictedElements in order to inform the NALocator of the restrictions of which the passed-in INAContext is currently aware. Subsequently, if any changes are made to solver restrictions, solver impedance attributes or solver barriers, be sure to call CacheRestrictedElements so that the locator can avoid locating on restricted network elements.

Note that it is appropriate to locate barriers on restricted elements. Therefore, when loading barriers, ExcludeRestrictedElements should be set to false. If loading is done via the NAClassLoader then the caller must call CacheRestrictedElements prior to using the NAClassLoader but the NAClassLoader will internally set ExcludeRestrictedElements to be false when loading any barrier NAClass.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

excludeRestricted - The excludeRestricted (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isExcludeRestrictedElements

boolean isExcludeRestrictedElements()
                                    throws IOException,
                                           AutomationException

Indicates whether to exclude restricted portions of the network when locating points.

Remarks

When ExcludeRestrictedElements is set to true, the INALocator location queries will not return network locations that fall on restricted network elements. The reason a network element could be restricted due to a point, polyline or polygon barrier, restriction network attributes, and/or elements with a negative impedance value.

If you set ExcludeRestrictedElements to true, then before calling any of the query location methods, be sure to call INALocator3::CacheRestrictedElements in order to inform the NALocator of the restrictions of which the passed-in INAContext is currently aware. Subsequently, if any changes are made to solver restrictions, solver impedance attributes or solver barriers, be sure to call CacheRestrictedElements so that the locator can avoid locating on restricted network elements.

Note that it is appropriate to locate barriers on restricted elements. Therefore, when loading barriers, ExcludeRestrictedElements should be set to false. If loading is done via the NAClassLoader then the caller must call CacheRestrictedElements prior to using the NAClassLoader but the NAClassLoader will internally set ExcludeRestrictedElements to be false when loading any barrier NAClass.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Returns:

The excludeRestricted

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

cacheRestrictedElements

void cacheRestrictedElements(INAContext context)
                             throws IOException,
                                    AutomationException

The locator will examine the NAContext and its associated NASolver to build a cache of network elements that cannot be located on due to restrictions, barriers, etc. This method should be called before querying the locator whenever ExcludeRestrictedElements i?U??&

Remarks

Use this method in conjunction with INALocator3::ExcludeRestrictedElements, in order to avoid loading locations on elements where travel is not allowed. If you set ExcludeRestrictedElements to true, then before calling any of the query location methods, be sure to call CacheRestrictedElements in order to inform the NALocator of the restrictions of which the passed-in NAContext is currently aware. Subsequently, if any changes are made to solver restrictions, impedances attributes or solver barriers, be sure to call CacheRestrictedElements so that the locator can avoid locating on restricted network elements.

Note that it is appropriate to locate barriers on restricted elements. Therefore, when loading barriers, ExcludeRestrictedElements should be set to false. If loading is done via the NAClassLoader then the caller must call CacheRestrictedElements prior to using the NAClassLoader but the NAClassLoader will internally set ExcludeRestrictedElements to be false when loading any barrier NAClass.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

context - A reference to a com.esri.arcgis.networkanalyst.INAContext (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

queryLocationByPointEx

void queryLocationByPointEx(IPoint point,
                            int curbApproach,
                            INALocation[] location,
                            IPoint[] outPoint,
                            double[] distanceFromPoint)
                            throws IOException,
                                   AutomationException

Use the locator agents to find a network location from a point and curb approach.

Remarks

QueryLocationByPointEx extends QueryLocationByPoint by adding a CurbApproach parameter.

Using the input Point object, this method calls QueryLocationByPointEx on each of its associated NALocatorAgent classes. The corresponding NALocation, the point where the location was found, and the distance from the input point to the source feature found are all returned.

If ExcludeRestrictedElements is set to true and CacheRestrictedElements has been called, then there is the possibility that a network edge is only traversable in one direction. In that case, the CurbApproach setting could render a location as unreachable. For example, if the along direction on an edge is restricted, and the location being queried would place the returned NALocation on the left side of the edge, then it is not possible to reach the stop with a vehicle requiring a CurbApproach of left side. QueryLocationByPointEx, in the above example, would switch the side of edge of the returned NALocation to right side, thereby allowing the NALocation to be reachable by vehicles with a CurbApproach requirement of left side.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

point - A reference to a com.esri.arcgis.geometry.IPoint (in)

curbApproach - A com.esri.arcgis.networkanalyst.esriNACurbApproachType constant (in)

location - A reference to a com.esri.arcgis.networkanalyst.INALocation (in/out: use single element array)

outPoint - A reference to a com.esri.arcgis.geometry.IPoint (in/out: use single element array)

distanceFromPoint - The distanceFromPoint (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

queryLocationByRowEx

void queryLocationByRowEx(IRow row,
                          int curbApproach,
                          INALocation[] location,
                          double[] distanceFromRow)
                          throws IOException,
                                 AutomationException

Use the locator agents to find a network location from a row and curb approach.

Remarks

QueryLocationByRowEx extends QueryLocationByRow by adding a CurbApproach parameter.

Using the inbound Row object, the method calls QueryLocationByRowEx on each of its associated NALocatorAgent classes. If FindClosestAmongAllAgents is false, it will return after the first locator succeeds in finding a location.

If ExcludeRestrictedElements is set to true and CacheRestrictedElements has been called, then there is the possibility that a network edge is only traversable in one direction. In that case, the CurbApproach setting could render a location as unreachable. For example, if the along direction on an edge is restricted, and the location being queried would place the returned NALocation on the left side of the edge, then it is not possible to reach the stop with a vehicle requiring a CurbApproach of left side. QueryLocationByRowEx, in the above example, would switch the side of edge of the returned NALocation to right side, thereby allowing the NALocation to be reachable by vehicles with a CurbApproach requirement of left side.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:

row - A reference to a com.esri.arcgis.geodatabase.IRow (in)

curbApproach - A com.esri.arcgis.networkanalyst.esriNACurbApproachType constant (in)

location - A reference to a com.esri.arcgis.networkanalyst.INALocation (in/out: use single element array)

distanceFromRow - The distanceFromRow (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.