com.esri.arcgis.networkanalyst
Class NALocator

java.lang.Object
  extended by com.esri.arcgis.networkanalyst.NALocator
All Implemented Interfaces:
com.esri.arcgis.interop.RemoteObjRef, INALocator, INALocator2, INALocator3, IClone, IPersist, IPersistStream, IXMLSerialize, Externalizable, Serializable

public class NALocator
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, INALocator, INALocator2, INALocator3, IPersistStream, IPersist, IClone, IXMLSerialize, Externalizable

Finds network locations for analysis.

Remarks

NALocator is a top-level container for managing and using network locators. It has a collection of Locator Agents that do the work of finding the locations.

While NALocators are CoCreateable, you typically get the NALocator from the NAContext, which sets up the locator appropriately for the network dataset and type of analysis.

Product Availability

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

See Also:
Serialized Form

Constructor Summary
NALocator()
          Constructs a NALocator using ArcGIS Engine.
NALocator(Object obj)
          Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
NALocator theNALocator = (NALocator) obj;
 
Method Summary
 void addLocatorAgent(INALocatorAgent locatorAgent)
          Add a locator agent.
 void assign(IClone src)
          Assigns the properties of src to the receiver.
 void bind(INetworkDataset pNetworkDataset, IGPMessages pGPMessages)
          Re-associate the locators with the given network dataset and its schema.
 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.
 void createDefault(IDENetworkDataset network)
          Make the default locators.
 void deserialize(IXMLSerializeData data)
          Deserializes an object from XML.
 boolean equals(Object o)
          Compare this object with another
 IClone esri_clone()
          Clones the receiver and assigns the result to *clone.
 INALocation geocodeLocation(String address, ILocator addressLocator)
          The network location at the specified address.
 void getClassID(GUID[] pClassID)
          getClassID
static String getClsid()
          getClsid.
 INALocatorAgent getLocatorAgent(int index)
          The locator agent by index.
 int getLocatorAgentCount()
          The number of locator agents added.
 double getMaxSnapTolerance()
          The maximum distance that can be searched when expanding the snap tolerance.
 INetworkDataset getNetworkDataset()
          The associated network dataset.
 ISpatialReference getOutputSpatialReference()
          The spatial reference for points returned by the locator.
 void getSizeMax(_ULARGE_INTEGER[] pcbSize)
          getSizeMax
 double getSnapTolerance()
          The distance to search.
 int getSnapToleranceUnits()
          The units of the snap tolerance.
 int hashCode()
          the hashcode for this object
 void isDirty()
          isDirty
 boolean isEqual(IClone other)
          Indicates if the receiver and other have the same properties.
 boolean isExcludeRestrictedElements()
          Indicates whether to exclude restricted portions of the network when locating points.
 boolean isFindClosestAmongAllAgents()
          Indicates if the closest location (only) should be returned.
 boolean isIdentical(IClone other)
          Indicates if the receiver and other are the same object.
 void load(IStream pstm)
          load
 void queryLocationByPoint(IPoint point, INALocation[] location, IPoint[] outPoint, double[] distanceFromPoint)
          Use the locator agents to find a network location from a point.
 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 queryLocationByRow(IRow row, INALocation[] location, double[] distanceFromRow)
          Use the locator agents to find a network location from a row.
 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 queryOffsetPoint(INALocation location, double offset, int units, IPoint[] point)
          The point offset from a network location.
 void queryPoint(INALocation location, IPoint[] point)
          The point for a network location.
 void readExternal(ObjectInput in)
           
 void removeLocatorAgent(int index)
          Remove a locator agent by index.
 String reverseGeocodeLocation(INALocation location, ILocator addressLocator)
          The address of the network location.
 void save(IStream pstm, int fClearDirty)
          save
 void serialize(IXMLSerializeData data)
          Serializes an object to XML.
 void setExcludeRestrictedElements(boolean excludeRestricted)
          Indicates whether to exclude restricted portions of the network when locating points.
 void setFindClosestAmongAllAgents(boolean findClosest)
          Indicates if the closest location (only) should be returned.
 void setMaxSnapTolerance(double maxTolerance)
          The maximum distance that can be searched when expanding the snap tolerance.
 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.
 void writeExternal(ObjectOutput out)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef
getJintegraDispatch, release
 

Constructor Detail

NALocator

public NALocator()
          throws IOException,
                 UnknownHostException
Constructs a NALocator using ArcGIS Engine.

Throws:
IOException - if there are interop problems
UnknownHostException - if there are interop problems

NALocator

public NALocator(Object obj)
          throws IOException
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
NALocator theNALocator = (NALocator) obj;

Construct a NALocator using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to NALocator.

Parameters:
obj - an object returned from ArcGIS Engine or Server
Throws:
IOException - if there are interop problems
Method Detail

getClsid

public static String getClsid()
getClsid.


equals

public boolean equals(Object o)
Compare this object with another

Overrides:
equals in class Object

hashCode

public int hashCode()
the hashcode for this object

Overrides:
hashCode in class Object

getNetworkDataset

public 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.

Specified by:
getNetworkDataset in interface INALocator
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

public 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.

Specified by:
setSnapTolerance in interface INALocator
Parameters:
tolerance - The tolerance (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSnapTolerance

public 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.

Specified by:
getSnapTolerance in interface INALocator
Returns:
The tolerance
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSnapToleranceUnits

public 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.

Specified by:
setSnapToleranceUnits in interface INALocator
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

public 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.

Specified by:
getSnapToleranceUnits in interface INALocator
Returns:
A com.esri.arcgis.system.esriUnits constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setFindClosestAmongAllAgents

public 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.

Specified by:
setFindClosestAmongAllAgents in interface INALocator
Parameters:
findClosest - The findClosest (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isFindClosestAmongAllAgents

public 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.

Specified by:
isFindClosestAmongAllAgents in interface INALocator
Returns:
The findClosest
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getLocatorAgentCount

public 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.

Specified by:
getLocatorAgentCount in interface INALocator
Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getLocatorAgent

public INALocatorAgent getLocatorAgent(int index)
                                throws IOException,
                                       AutomationException
The locator agent by index.

Product Availability

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

Specified by:
getLocatorAgent in interface INALocator
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

public 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.

Specified by:
createDefault in interface INALocator
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

public 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.

Specified by:
addLocatorAgent in interface INALocator
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

public 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.

Specified by:
removeLocatorAgent in interface INALocator
Parameters:
index - The index (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryLocationByPoint

public 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.

Specified by:
queryLocationByPoint in interface INALocator
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

public 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.

Specified by:
queryLocationByRow in interface INALocator
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

public 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.

Specified by:
queryPoint in interface INALocator
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

public 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.

Specified by:
bind in interface INALocator
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

public 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.

Specified by:
setOutputSpatialReferenceByRef in interface INALocator
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

public 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.

Specified by:
getOutputSpatialReference in interface INALocator
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.

getMaxSnapTolerance

public double getMaxSnapTolerance()
                           throws IOException,
                                  AutomationException
The maximum distance that can be searched when expanding the snap tolerance. Has the same units as the snap tolerance.

Remarks

The INALocator::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 MaxSnapTolerance is reached.

Product Availability

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

Specified by:
getMaxSnapTolerance in interface INALocator2
Returns:
The maxTolerance
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMaxSnapTolerance

public void setMaxSnapTolerance(double maxTolerance)
                         throws IOException,
                                AutomationException
The maximum distance that can be searched when expanding the snap tolerance. Has the same units as the snap tolerance.

Remarks

The INALocator::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 MaxSnapTolerance is reached.

Product Availability

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

Specified by:
setMaxSnapTolerance in interface INALocator2
Parameters:
maxTolerance - The maxTolerance (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryOffsetPoint

public void queryOffsetPoint(INALocation location,
                             double offset,
                             int units,
                             IPoint[] point)
                      throws IOException,
                             AutomationException
The point offset from a network location.

Remarks

QueryOffsetPoint returns the spatial location of an NALocation after applying the offset distance and units specified. If the location occurs along a line, the (input location parameter) INALocation.Side property indicates whether the offset occurs to the left or right of the digitized direction of the line. In other words, if the location is on the left side, the offset occurs to the left. For locations on junctions, nothing is offset.

Generally, the NALocator 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 agents and associate it with the NetworkDataset.

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.

Specified by:
queryOffsetPoint in interface INALocator2
Parameters:
location - A reference to a com.esri.arcgis.networkanalyst.INALocation (in)
offset - The offset (in)
units - A com.esri.arcgis.system.esriUnits constant (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.

reverseGeocodeLocation

public String reverseGeocodeLocation(INALocation location,
                                     ILocator addressLocator)
                              throws IOException,
                                     AutomationException
The address of the network location. Honors side of street if the address locator does.

Remarks

ReverseGeocodeLocation returns the text address of an NALocation based on the address locator specified.

Product Availability

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

Specified by:
reverseGeocodeLocation in interface INALocator2
Parameters:
location - A reference to a com.esri.arcgis.networkanalyst.INALocation (in)
addressLocator - A reference to a com.esri.arcgis.geodatabase.ILocator (in)
Returns:
The address
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

geocodeLocation

public INALocation geocodeLocation(String address,
                                   ILocator addressLocator)
                            throws IOException,
                                   AutomationException
The network location at the specified address. Honors side of street if the address locator does.

Remarks

GeocodeLocation returns an NALocation based on the input address and address locator specfied.

It does this by using the point returned by the address locator and then iterating through the NALocator's locator agents calling QueryLocationByPoint.

Product Availability

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

Specified by:
geocodeLocation in interface INALocator2
Parameters:
address - The address (in)
addressLocator - A reference to a com.esri.arcgis.geodatabase.ILocator (in)
Returns:
A reference to a com.esri.arcgis.networkanalyst.INALocation
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryLocationRangesByGeometry

public 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.

Specified by:
queryLocationRangesByGeometry in interface INALocator3
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

public 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.

Specified by:
queryLocationRangesByRow in interface INALocator3
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

public 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.

Specified by:
setExcludeRestrictedElements in interface INALocator3
Parameters:
excludeRestricted - The excludeRestricted (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isExcludeRestrictedElements

public 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.

Specified by:
isExcludeRestrictedElements in interface INALocator3
Returns:
The excludeRestricted
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

cacheRestrictedElements

public 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?Ÿ??&

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.

Specified by:
cacheRestrictedElements in interface INALocator3
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

public 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.

Specified by:
queryLocationByPointEx in interface INALocator3
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

public 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.

Specified by:
queryLocationByRowEx in interface INALocator3
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.

isDirty

public void isDirty()
             throws IOException,
                    AutomationException
isDirty

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isDirty in interface IPersistStream
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

load

public void load(IStream pstm)
          throws IOException,
                 AutomationException
load

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
load in interface IPersistStream
Parameters:
pstm - A reference to a com.esri.arcgis.system.IStream (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

save

public void save(IStream pstm,
                 int fClearDirty)
          throws IOException,
                 AutomationException
save

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
save in interface IPersistStream
Parameters:
pstm - A reference to a com.esri.arcgis.system.IStream (in)
fClearDirty - The fClearDirty (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSizeMax

public void getSizeMax(_ULARGE_INTEGER[] pcbSize)
                throws IOException,
                       AutomationException
getSizeMax

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSizeMax in interface IPersistStream
Parameters:
pcbSize - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getClassID

public void getClassID(GUID[] pClassID)
                throws IOException,
                       AutomationException
getClassID

Description

IPersist is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getClassID in interface IPersist
Parameters:
pClassID - A Structure: com.esri.arcgis.support.ms.stdole.GUID (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

esri_clone

public IClone esri_clone()
                  throws IOException,
                         AutomationException
Clones the receiver and assigns the result to *clone.

Product Availability

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

Specified by:
esri_clone in interface IClone
Returns:
A reference to a com.esri.arcgis.system.IClone
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

assign

public void assign(IClone src)
            throws IOException,
                   AutomationException
Assigns the properties of src to the receiver.

Description

Use Assign method to assign the properties of source object to receiver object. Both objects need to have the same CLSIDs. Both source and receiver objects need to be instantiated.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
assign in interface IClone
Parameters:
src - A reference to a com.esri.arcgis.system.IClone (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isEqual

public boolean isEqual(IClone other)
                throws IOException,
                       AutomationException
Indicates if the receiver and other have the same properties.

Description

IsEqual returns True if the receiver and the source have the same properties. Note, this does not imply that the receiver and the source reference the same object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isEqual in interface IClone
Parameters:
other - A reference to a com.esri.arcgis.system.IClone (in)
Returns:
The equal
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isIdentical

public boolean isIdentical(IClone other)
                    throws IOException,
                           AutomationException
Indicates if the receiver and other are the same object.

Description

IsIdentical returns true if the receiver and the source reference the same object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isIdentical in interface IClone
Parameters:
other - A reference to a com.esri.arcgis.system.IClone (in)
Returns:
The identical
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

serialize

public void serialize(IXMLSerializeData data)
               throws IOException,
                      AutomationException
Serializes an object to XML.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
serialize in interface IXMLSerialize
Parameters:
data - A reference to a com.esri.arcgis.system.IXMLSerializeData (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

deserialize

public void deserialize(IXMLSerializeData data)
                 throws IOException,
                        AutomationException
Deserializes an object from XML.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
deserialize in interface IXMLSerialize
Parameters:
data - A reference to a com.esri.arcgis.system.IXMLSerializeData (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException
Specified by:
writeExternal in interface Externalizable
Throws:
IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException
Specified by:
readExternal in interface Externalizable
Throws:
IOException
ClassNotFoundException