com.esri.arcgis.geodatabase
Class NetworkFunctionEvaluator

java.lang.Object
  extended by com.esri.arcgis.geodatabase.NetworkFunctionEvaluator
All Implemented Interfaces:
IGPDescribe, INetworkEvaluator, INetworkEvaluator2, INetworkEvaluatorSetup, INetworkFunctionEvaluator, com.esri.arcgis.interop.RemoteObjRef, Serializable

public class NetworkFunctionEvaluator
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, INetworkEvaluator, INetworkEvaluator2, INetworkEvaluatorSetup, INetworkFunctionEvaluator, IGPDescribe

A container for describing a network evaluator function.

Description

This object is new at ArcGIS 9.3.

A NetworkFunctionEvaluator is an evaluator that assigns network attribute values by scaling or comparing the value of another attribute or parameter. Below are examples of expressions:

The NetworkFunctionEvaluator has its CacheAttribute property equal to False, unlike the NetworkConstantEvaluator and NetworkFieldEvaluator. This means that it does not evaluate its expression when the network is built, but when a network solver requires the result of that calculation. It is designed for dynamic analysis of a network under changing conditions.

Product Availability

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

See Also:
Serialized Form

Constructor Summary
NetworkFunctionEvaluator()
          Constructs a NetworkFunctionEvaluator using ArcGIS Engine.
NetworkFunctionEvaluator(Object obj)
          Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
NetworkFunctionEvaluator theNetworkFunctionEvaluator = (NetworkFunctionEvaluator) obj;
 
Method Summary
 Object describe(String name)
          The description of the named object.
 boolean equals(Object o)
          Compare this object with another
static String getClsid()
          getClsid.
 IUID getCLSID()
          Unique CLSID identifier for this network evaluator.
 IPropertySet getData()
          The data used by this network evaluator for custom properties.
 String getDisplayName()
          Name displayed in the user interface for this network evaluator.
 Object getFirstArgument()
          The attribute name or constant value representing the first argument of the function.
 String getName()
          Unique name of this network evaluator.
 String getOperator()
          The operator used in the function.
 IEnumBSTR getOperators(int returnDataType)
          Get the list of supported binary operator names.
 IStringArray getRequiredFieldNames()
          Required fields of this network evaluator.
 Object getSecondArgument()
          The parameter name or constant value representing the second argument of the function.
 int hashCode()
          the hashcode for this object
 void initialize(INetworkDataset networkDataset, IDENetworkDataset dataElement, INetworkSource source, IEvaluatedNetworkAttribute attribute)
          Initializes the network evaluator in preparation to evaluate the attribute value of a network element.
 boolean isCacheAttribute()
          Indicates if this evaluator's values should be computed and stored when the network is built or computed at run time and never stored.
 boolean isDataHasEdits()
          Indicates if the data for this evaluator has been edited.
 Object queryValue(INetworkElement element, IRow row)
          Evaluates the attribute value of a network element.
 void refresh()
          Refresh custom data for this network evaluator to synchronize with updated attribute parameter values or other external data.
 void setData(IPropertySet data)
          The data used by this network evaluator for custom properties.
 void setFirstArgument(Object arg1)
          The attribute name or constant value representing the first argument of the function.
 void setOperator(String op)
          The operator used in the function.
 void setSecondArgument(Object arg2)
          The parameter name or constant value representing the second argument of the function.
 boolean supportsDefault(int elementType, IEvaluatedNetworkAttribute attribute)
          Indicates if this network evaluator can be used as the default evaluator for the given network element type and network attribute.
 boolean supportsSource(INetworkSource source, IEvaluatedNetworkAttribute attribute)
          Indicates if this network evaluator can be used as the evaluator for the given network source and network attribute.
 boolean validateDefault(int elementType, IEvaluatedNetworkAttribute attribute, int[] errorCode, String[] errorDescription, String[] errorAppendInfo)
          Indicates if the network evaluator is in a valid state for use as the default evaluator for the given element type and network attribute.
 boolean validateSource(IDatasetContainer2 datasetContainer, INetworkSource networkSource, IEvaluatedNetworkAttribute attribute, int[] errorCode, String[] errorDescription, String[] errorAppendInfo)
          Indicates if the network evaluator is in a valid state for use as the evaluator for the given network source and network attribute.
 
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

NetworkFunctionEvaluator

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

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

NetworkFunctionEvaluator

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

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

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

getName

public String getName()
               throws IOException,
                      AutomationException
Unique name of this network evaluator.

Product Availability

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

Specified by:
getName in interface INetworkEvaluator
Returns:
The pName
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getDisplayName

public String getDisplayName()
                      throws IOException,
                             AutomationException
Name displayed in the user interface for this network evaluator.

Remarks

The DisplayName is the name for the evaluator that will be displayed in the Type column of the Evaluators dialog in ArcCatalog.

Product Availability

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

Specified by:
getDisplayName in interface INetworkEvaluator
Returns:
The pDisplayName
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isCacheAttribute

public boolean isCacheAttribute()
                         throws IOException,
                                AutomationException
Indicates if this evaluator's values should be computed and stored when the network is built or computed at run time and never stored.

Remarks

The CacheAttribute property determines whether the values computed by this evaluator are stored in the logical network of the network dataset.

If the CacheAttribute property is set to True, then the attribute values are computed by the evaluator only when the network is built. The computed attribute values are then stored in the logical network. When a client queries for attribute values (such as during a network analysis), the attribute values are retrieved from the logical network.

If the CacheAttribute property is set to False, then the attribute values are computed by the evaluator whenever any client asks for an attribute value (such as during a network analysis). The computed attribute values are not stored in the logical network. Depending on the complexity of the evaluator, this operation can be much slower than looking up values stored in the logical network.

Product Availability

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

Specified by:
isCacheAttribute in interface INetworkEvaluator
Returns:
The cache
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRequiredFieldNames

public IStringArray getRequiredFieldNames()
                                   throws IOException,
                                          AutomationException
Required fields of this network evaluator.

Remarks

RequiredFieldNames returns the field names that the evaluator requires in order to correctly evaluate the row. This property is used to minimize the data that is returned by the query to the database by only returning the required fields. Return a NULL pointer if you want it to include all the field names in the query.

Product Availability

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

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

refresh

public void refresh()
             throws IOException,
                    AutomationException
Refresh custom data for this network evaluator to synchronize with updated attribute parameter values or other external data.

Remarks

The Refresh method is an opportunity to update any internal state within the evaluator based on changes to parameters, dynamic data feeds, etc. The Refresh method is called on every evaluator assigned to a network attribute when INetworkAttribute2::Refresh() is called. For example, this is called internally during a solve operation after setting the network attribute parameters and prior to performing the actual solve.

Product Availability

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

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

initialize

public void initialize(INetworkDataset networkDataset,
                       IDENetworkDataset dataElement,
                       INetworkSource source,
                       IEvaluatedNetworkAttribute attribute)
                throws IOException,
                       AutomationException
Initializes the network evaluator in preparation to evaluate the attribute value of a network element.

Remarks

The Initialize method does all the "heavy lifting" needed to prepare the evaluator for a call to QueryValue, a lightweight method for querying the attribute value for a network element. Once the evaluator is initialized, the client can make multiple calls to this lightweight QueryValue for calculating the attribute values of multiple network elements.

When querying for attribute values in the network dataset ArcGIS calls the Initialize method immediately after it instantiates the evaluator. For evaluators with CacheAttribute = True, this occurs when building the network dataset. For evaluators with CacheAttribute = False, this occurs on the first call in the session to INetworkElement::AttributeValue or ::AttributeValueByName that requires this evaluator to determine the attribute value.

Product Availability

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

Specified by:
initialize in interface INetworkEvaluatorSetup
Parameters:
networkDataset - A reference to a com.esri.arcgis.geodatabase.INetworkDataset (in)
dataElement - A reference to a com.esri.arcgis.geodatabase.IDENetworkDataset (in)
source - A reference to a com.esri.arcgis.geodatabase.INetworkSource (in)
attribute - A reference to a com.esri.arcgis.geodatabase.IEvaluatedNetworkAttribute (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setData

public void setData(IPropertySet data)
             throws IOException,
                    AutomationException
The data used by this network evaluator for custom properties.

Product Availability

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

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

getData

public IPropertySet getData()
                     throws IOException,
                            AutomationException
The data used by this network evaluator for custom properties.

Remarks

The Data property stores data that is needed by the evaluator. It is stored in a PropertySet object using key-value pairs.

Product Availability

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

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

isDataHasEdits

public boolean isDataHasEdits()
                       throws IOException,
                              AutomationException
Indicates if the data for this evaluator has been edited.

Remarks

The DataHasEdits property indicates whether changes have been made to the Data PropertySet that have not yet been handled by the evaluator's internal logic. This is useful in determining whether the evaluator needs to be re-Initialized before making additional calls to QueryValue.

This property is only used when modifying the network dataset's evaluators via objects like the EvaluatorEditor to signify the network dataset may need to be rebuilt/reinitialized. This property is not queried prior to network analysis to determine if the evaluator needs to be re-initialized. Thus, it is not a mechanism to trigger that the evaluators need to be re-initialized based on new data between solves.

Product Availability

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

Specified by:
isDataHasEdits in interface INetworkEvaluatorSetup
Returns:
The hasEdits
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getCLSID

public IUID getCLSID()
              throws IOException,
                     AutomationException
Unique CLSID identifier for this network evaluator.

Product Availability

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

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

supportsSource

public boolean supportsSource(INetworkSource source,
                              IEvaluatedNetworkAttribute attribute)
                       throws IOException,
                              AutomationException
Indicates if this network evaluator can be used as the evaluator for the given network source and network attribute.

Remarks

TheSupportsSource method is used to determine if the evaluator can be used to assign attribute values for elements generated by the given source. If SupportsSource is False, then the evaluator does not show up as a choice for the user in the Evaluators dialog in ArcCatalog.

Product Availability

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

Specified by:
supportsSource in interface INetworkEvaluatorSetup
Parameters:
source - A reference to a com.esri.arcgis.geodatabase.INetworkSource (in)
attribute - A reference to a com.esri.arcgis.geodatabase.IEvaluatedNetworkAttribute (in)
Returns:
The isSupported
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

supportsDefault

public boolean supportsDefault(int elementType,
                               IEvaluatedNetworkAttribute attribute)
                        throws IOException,
                               AutomationException
Indicates if this network evaluator can be used as the default evaluator for the given network element type and network attribute.

Remarks

The SupportsDefault method is used to determine if the evaluator can be used to assign default attribute values for elements of the given type. If SupportsDefault is False, then the evaluator does not show up as a default evaluator choice for the user in the Evaluators dialog in ArcCatalog.

Product Availability

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

Specified by:
supportsDefault in interface INetworkEvaluatorSetup
Parameters:
elementType - A com.esri.arcgis.geodatabase.esriNetworkElementType constant (in)
attribute - A reference to a com.esri.arcgis.geodatabase.IEvaluatedNetworkAttribute (in)
Returns:
The isSupported
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

validateSource

public boolean validateSource(IDatasetContainer2 datasetContainer,
                              INetworkSource networkSource,
                              IEvaluatedNetworkAttribute attribute,
                              int[] errorCode,
                              String[] errorDescription,
                              String[] errorAppendInfo)
                       throws IOException,
                              AutomationException
Indicates if the network evaluator is in a valid state for use as the evaluator for the given network source and network attribute.

Product Availability

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

Specified by:
validateSource in interface INetworkEvaluatorSetup
Parameters:
datasetContainer - A reference to a com.esri.arcgis.geodatabase.IDatasetContainer2 (in)
networkSource - A reference to a com.esri.arcgis.geodatabase.INetworkSource (in)
attribute - A reference to a com.esri.arcgis.geodatabase.IEvaluatedNetworkAttribute (in)
errorCode - The errorCode (in/out: use single element array)
errorDescription - The errorDescription (in/out: use single element array)
errorAppendInfo - The errorAppendInfo (in/out: use single element array)
Returns:
The isValid
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

validateDefault

public boolean validateDefault(int elementType,
                               IEvaluatedNetworkAttribute attribute,
                               int[] errorCode,
                               String[] errorDescription,
                               String[] errorAppendInfo)
                        throws IOException,
                               AutomationException
Indicates if the network evaluator is in a valid state for use as the default evaluator for the given element type and network attribute.

Product Availability

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

Specified by:
validateDefault in interface INetworkEvaluatorSetup
Parameters:
elementType - A com.esri.arcgis.geodatabase.esriNetworkElementType constant (in)
attribute - A reference to a com.esri.arcgis.geodatabase.IEvaluatedNetworkAttribute (in)
errorCode - The errorCode (in/out: use single element array)
errorDescription - The errorDescription (in/out: use single element array)
errorAppendInfo - The errorAppendInfo (in/out: use single element array)
Returns:
The isValid
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

queryValue

public Object queryValue(INetworkElement element,
                         IRow row)
                  throws IOException,
                         AutomationException
Evaluates the attribute value of a network element.

Remarks

QueryValue uses this evaluator to compute the attribute value for the given network element.

The Row parameter is provided in order to query any information from the Row (such as field values) corresponding to the given network element when building the network dataset. When computing attribute values that will be cached within the network, QueryValue is automatically called by the system, and the Row from the corresponding source feature will be passed into QueryValue.

Note that QueryValue is also automatically called by the system when querying non-cached attribute values by using the INetworkElement interface. In this situation, the Row parameter will always be null; that is, the Row from the corresponding source feature will not be passed into QueryValue.

Before calling QueryValue, the evaluator must first be initialized by calling the Initialize method. After calling Initialize, QueryValue can be called multiple times to calculate attribute values for multiple network elements.

Product Availability

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

Specified by:
queryValue in interface INetworkEvaluatorSetup
Parameters:
element - A reference to a com.esri.arcgis.geodatabase.INetworkElement (in)
row - A reference to a com.esri.arcgis.geodatabase.IRow (in)
Returns:
A Variant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setFirstArgument

public void setFirstArgument(Object arg1)
                      throws IOException,
                             AutomationException
The attribute name or constant value representing the first argument of the function.

Product Availability

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

Specified by:
setFirstArgument in interface INetworkFunctionEvaluator
Parameters:
arg1 - A Variant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getFirstArgument

public Object getFirstArgument()
                        throws IOException,
                               AutomationException
The attribute name or constant value representing the first argument of the function.

Remarks

The FirstArgument must be the name of a NetworkAttribute or a constant value.

If the FirstArgument is a constant value, it should be of the same DataType for the network attribute to which this evaluator is assigned.

Product Availability

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

Specified by:
getFirstArgument in interface INetworkFunctionEvaluator
Returns:
A Variant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setOperator

public void setOperator(String op)
                 throws IOException,
                        AutomationException
The operator used in the function.

Product Availability

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

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

getOperator

public String getOperator()
                   throws IOException,
                          AutomationException
The operator used in the function.

Remarks

The Operator must be set to one of the operators returned in GetOperators.

Product Availability

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

Specified by:
getOperator in interface INetworkFunctionEvaluator
Returns:
The op
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSecondArgument

public void setSecondArgument(Object arg2)
                       throws IOException,
                              AutomationException
The parameter name or constant value representing the second argument of the function.

Remarks

The SecondArgument must be the name of a NetworkAttributeParameter or a constant value.

If the SecondArgument is a constant value, it should be of the same DataType for the network attribute to which this evaluator is assigned.

Product Availability

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

Specified by:
setSecondArgument in interface INetworkFunctionEvaluator
Parameters:
arg2 - A Variant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSecondArgument

public Object getSecondArgument()
                         throws IOException,
                                AutomationException
The parameter name or constant value representing the second argument of the function.

Remarks

The SecondArgument must be the name of a NetworkAttributeParameter or a constant value.

If the SecondArgument is a constant value, it should be of the same DataType for the network attribute to which this evaluator is assigned.

Product Availability

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

Specified by:
getSecondArgument in interface INetworkFunctionEvaluator
Returns:
A Variant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getOperators

public IEnumBSTR getOperators(int returnDataType)
                       throws IOException,
                              AutomationException
Get the list of supported binary operator names.

Remarks

GetOperators returned the list of valid operators that can be used in a NetworkFunctionEvaluator for a given network attribute DataType.

For numeric data types, the valid operators are:

For the Boolean data type, the valid operators are

Product Availability

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

Specified by:
getOperators in interface INetworkFunctionEvaluator
Parameters:
returnDataType - A com.esri.arcgis.geodatabase.esriNetworkAttributeDataType constant (in)
Returns:
A reference to a com.esri.arcgis.system.IEnumBSTR
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

describe

public Object describe(String name)
                throws IOException,
                       AutomationException
The description of the named object.

Product Availability

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

Specified by:
describe in interface IGPDescribe
Parameters:
name - The name (in)
Returns:
A Variant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.