com.esri.arcgis.networkanalyst
Interface INALocator

All Superinterfaces:
Serializable
All Known Subinterfaces:
INALocator2
All Known Implementing Classes:
NALocator

public interface INALocator
extends Serializable

Provides access to properties that apply to all network locators.

Superseded By

INALocator2

Remarks

The INALocator interface searches for network locations and queries the results of a search.

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.

This method will return an error if the NALocator has already been tied to a network dataset using the Bind method.

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.