com.esri.arcgis.networkanalyst
Interface INALocator

All Superinterfaces:

Serializable

All Known Subinterfaces:

INALocator2, INALocator3

All Known Implementing Classes:

NALocator

public interface INALocator
extends Serializable

Provides access to properties that apply to all network locators.

Superseded By

INALocator2

Remarks

INALocator has been superseded by INALocator3.

Product Availability

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

Method Summary

void	addLocatorAgent(INALocatorAgent locatorAgent) Add a locator agent.
void	bind(INetworkDataset pNetworkDataset, IGPMessages pGPMessages) Re-associate the locators with the given network dataset and its schema.
void	createDefault(IDENetworkDataset network) Make the default locators.
INALocatorAgent	getLocatorAgent(int index) The locator agent by index.
int	getLocatorAgentCount() The number of locator agents added.
INetworkDataset	getNetworkDataset() The associated network dataset.
ISpatialReference	getOutputSpatialReference() The spatial reference for points returned by the locator.
double	getSnapTolerance() The distance to search.
int	getSnapToleranceUnits() The units of the snap tolerance.
boolean	isFindClosestAmongAllAgents() Indicates if the closest location (only) should be returned.
void	queryLocationByPoint(IPoint point, INALocation[] location, IPoint[] outPoint, double[] distanceFromPoint) Use the locator agents to find a network location from a point.
void	queryLocationByRow(IRow row, INALocation[] location, double[] distanceFromRow) Use the locator agents to find a network location from a row.
void	queryPoint(INALocation location, IPoint[] point) The point for a network location.
void	removeLocatorAgent(int index) Remove a locator agent by index.
void	setFindClosestAmongAllAgents(boolean findClosest) Indicates if the closest location (only) should be returned.
void	setOutputSpatialReferenceByRef(ISpatialReference spatialReference) The spatial reference for points returned by the locator.
void	setSnapTolerance(double tolerance) The distance to search.
void	setSnapToleranceUnits(int units) The units of the snap tolerance.

Method Detail

getNetworkDataset

INetworkDataset getNetworkDataset()
                                  throws IOException,
                                         AutomationException

The associated network dataset.

Remarks

The NetworkDataset property holds a reference to the NetworkDataset that the locator is bound to and is used for locating network locations. The property is set by calling INALocator::Bind.

Product Availability

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

Returns:

A reference to a com.esri.arcgis.geodatabase.INetworkDataset

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSnapTolerance

void setSnapTolerance(double tolerance)
                      throws IOException,
                             AutomationException

The distance to search.

Remarks

The SnapTolerance property specifies the minimum search tolerance used when finding network locations. If nothing is found within this tolerance, the search tolerance is doubled until a network location is found or INALocator2::MaxSnapTolerance is reached.

Product Availability

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

Parameters:

tolerance - The tolerance (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSnapTolerance

double getSnapTolerance()
                        throws IOException,
                               AutomationException

The distance to search.

Remarks

The SnapTolerance property specifies the minimum search tolerance used when finding network locations. If nothing is found within this tolerance, the search tolerance is doubled until a network location is found or INALocator2::MaxSnapTolerance is reached.

Product Availability

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

Returns:

The tolerance

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSnapToleranceUnits

void setSnapToleranceUnits(int units)
                           throws IOException,
                                  AutomationException

The units of the snap tolerance.

Remarks

SnapToleranceUnits determines how the SnapTolerance number is interpreted.

Product Availability

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

Parameters:

units - A com.esri.arcgis.system.esriUnits constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSnapToleranceUnits

int getSnapToleranceUnits()
                          throws IOException,
                                 AutomationException

The units of the snap tolerance.

Remarks

SnapToleranceUnits determines how the SnapTolerance number is interpreted.

Product Availability

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

Returns:

A com.esri.arcgis.system.esriUnits constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setFindClosestAmongAllAgents

void setFindClosestAmongAllAgents(boolean findClosest)
                                  throws IOException,
                                         AutomationException

Indicates if the closest location (only) should be returned.

Remarks

FindClosestAmongAllAgents specifies if you want to search among all locator agents or not.

When you have many network sources, you may want to stop once you find a location within the search tolerance of one of the agents. If this is the case, set FindClosestAmongAllAgents to false and the first locator to find a location will stop the search.

Product Availability

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

Parameters:

findClosest - The findClosest (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isFindClosestAmongAllAgents

boolean isFindClosestAmongAllAgents()
                                    throws IOException,
                                           AutomationException

Indicates if the closest location (only) should be returned.

Remarks

FindClosestAmongAllAgents specifies if you want to search among all locator agents or not.

When you have many network sources, you may want to stop once you find a location within the search tolerance of one of the agents. If this is the case, set FindClosestAmongAllAgents to false and the first locator to find a location will stop the search.

Product Availability

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

Returns:

The findClosest

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLocatorAgentCount

int getLocatorAgentCount()
                         throws IOException,
                                AutomationException

The number of locator agents added.

Remarks

LocatorAgentCount returns the number of locator agents that the NALocator is referencing.

Product Availability

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

Returns:

The count

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLocatorAgent

INALocatorAgent getLocatorAgent(int index)
                                throws IOException,
                                       AutomationException

The locator agent by index.

Product Availability

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

Parameters:

index - The index (in)

Returns:

A reference to a com.esri.arcgis.networkanalyst.INALocatorAgent

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

createDefault

void createDefault(IDENetworkDataset network)
                   throws IOException,
                          AutomationException

Make the default locators.

Remarks

CreateDefault will examine the network sources for the inbound network dataset and set up a locator agent for each source as appropriate. Each locator agent is then added to the LocatorAgent collection of the NALocator. Sources that do not support NALocations, like Turn and Hyperedge sources, will not have a locator agent.

Product Availability

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

Parameters:

network - A reference to a com.esri.arcgis.geodatabase.IDENetworkDataset (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

addLocatorAgent

void addLocatorAgent(INALocatorAgent locatorAgent)
                     throws IOException,
                            AutomationException

Add a locator agent.

Remarks

AddLocatorAgent adds a locator agent to the NALocator's collection.

Product Availability

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

Parameters:

locatorAgent - A reference to a com.esri.arcgis.networkanalyst.INALocatorAgent (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

removeLocatorAgent

void removeLocatorAgent(int index)
                        throws IOException,
                               AutomationException

Remove a locator agent by index.

Remarks

RemoveLocatorAgent removes a locator agent from the NALocator's collection.

Product Availability

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

Parameters:

index - The index (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

queryLocationByPoint

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

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

Remarks

Using the input Point object, this method calls QueryLocationByPoint 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.

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.

QueryLocationByPoint searches for network locations based upon an input point. When the NALocatorFeatureAgent is used, the distance returned is from the point to the feature, not from the point to the actual network location on the feature. It is important to know the distance to the feature as a whole because this is the feature on which you want to locate the endpoint/midpoint. If you need to determine the distance from the input point to the actual network location point, use IProximityOperator::ReturnDistance between the input point and the output point.

If FindClosestAmongAllAgents is false, it will return after the first locator succeeds in finding a location.

The output geometry is returned in the spatial reference of the network dataset. Optionally, set an OutputSpatialReference on the NALocator.

Product Availability

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

Parameters:

point - A reference to a com.esri.arcgis.geometry.IPoint (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.

queryLocationByRow

void queryLocationByRow(IRow row,
                        INALocation[] location,
                        double[] distanceFromRow)
                        throws IOException,
                               AutomationException

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

Description

Remarks

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

Product Availability

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

Parameters:

row - A reference to a com.esri.arcgis.geodatabase.IRow (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.

queryPoint

void queryPoint(INALocation location,
                IPoint[] point)
                throws IOException,
                       AutomationException

The point for a network location.

Remarks

QueryPoint returns the spatial location of an NALocation. This method may be used after calling QueryLocationByRow in order to get its spatial location.

The output geometry is returned in the spatial reference of the network dataset. Optionally set an OutputSpatialReference on the NALocator.

Product Availability

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

Parameters:

location - A reference to a com.esri.arcgis.networkanalyst.INALocation (in)

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

bind

void bind(INetworkDataset pNetworkDataset,
          IGPMessages pGPMessages)
          throws IOException,
                 AutomationException

Re-associate the locators with the given network dataset and its schema.

Remarks

Bind will associate all of the contained NALocator objects with the input network dataset specified. This method must be called before calling any of the Query functions.

Product Availability

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

Parameters:

pNetworkDataset - A reference to a com.esri.arcgis.geodatabase.INetworkDataset (in)

pGPMessages - A reference to a com.esri.arcgis.geodatabase.IGPMessages (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setOutputSpatialReferenceByRef

void setOutputSpatialReferenceByRef(ISpatialReference spatialReference)
                                    throws IOException,
                                           AutomationException

The spatial reference for points returned by the locator.

Product Availability

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

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getOutputSpatialReference

ISpatialReference getOutputSpatialReference()
                                            throws IOException,
                                                   AutomationException

The spatial reference for points returned by the locator.

Remarks

The OutputSpatialReference property determines the spatial reference used for results.

If the OutputSpatialReference for a NALocator attached to a NAContext is set as null, it is assumed to be the same as the spatial reference of the network dataset to which the NAContext is bound.

Product Availability

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

Returns:

A reference to a com.esri.arcgis.geometry.ISpatialReference

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.