com.esri.arcgis.trackinganalyst
Class TemporalQueryFilter

java.lang.Object
  extended by com.esri.arcgis.trackinganalyst.TemporalQueryFilter
All Implemented Interfaces:
IQueryFilter, IQueryFilter2, IQueryFilterDefinition, ISpatialFilter, ITemporalQueryFilter, ITemporalQueryFilter2, com.esri.arcgis.interop.RemoteObjRef, IClone, IDocumentVersionSupportGEN, IPersist, IPersistStream, ISupportErrorInfo, IXMLSerialize, Externalizable, Serializable

public class TemporalQueryFilter
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, ITemporalQueryFilter, ITemporalQueryFilter2, ISpatialFilter, IClone, ISupportErrorInfo, IPersist, IPersistStream, IQueryFilter, IQueryFilter2, IQueryFilterDefinition, IXMLSerialize, IDocumentVersionSupportGEN, Externalizable

Controls properties for the temporal query filter.

Description

This object controls properties for the temporal query filter. Users can control properties like starting and ending dates, temporal order, temporal relationship, temporal conversion and where clause. Users can also clone the temporal query filter, assign the temporal query filter to another filter, compare if two temporal query filters are identical.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server. Requires Tracking Analyst Extension.

See Also:
Serialized Form

Constructor Summary
TemporalQueryFilter()
          Constructs a TemporalQueryFilter using ArcGIS Engine.
TemporalQueryFilter(Object obj)
          Construct a TemporalQueryFilter using a reference to such an object returned from ArcGIS Engine or Server.
 
Method Summary
 void addField(String subField)
          Appends a single field name to the list of sub-fields.
 void assign(IClone src)
          Assigns the properties of src to the receiver.
 Object convertToSupportedObject(int docVersion)
          Convert the object to another object that is supported.
 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.
 void getClassID(GUID[] pClassID)
          getClassID
static String getClsid()
          getClsid.
 Object getEndingDate()
          Indicates the latest date included in the query.
 IFilterDefs getFilterDefs()
          The filter definitions specified for this query filter.
 IGeometry getGeometry()
          The query geometry used to filter results.
 String getGeometryField()
          The name of the Geometry field to which the filter applies.
 ISpatialReference getOutputSpatialReference(String fieldName)
          The spatial reference in which to output geometry for a given field.
 String getPostfixClause()
          A clause that will be appended to the SELECT statement, following the where clause.
 ITemporalOperator getRelativeTimeOperator()
          The object that contains a relative time to offset the temporal values.
 int getSearchOrder()
          The search order used by the filter.
 void getSizeMax(_ULARGE_INTEGER[] pcbSize)
          getSizeMax
 int getSpatialRel()
          The spatial relationship checked by the filter.
 String getSpatialRelDescription()
          The array elements which describe the spatial relation between the query geometry and the requested geometries.
 double getSpatialResolution()
          The spatial resolution in which to output geometry.
 Object getStartingDate()
          Indicates the earliest date included in the query.
 String getSubFields()
          The comma delimited list of field names for the filter.
 int getTemporalConversion()
          The temporal conversion mode to use (if any) by the temporal query.
 int getTemporalOrder()
          Defines order in which temporal records are sorted.
 int getTemporalRelationship()
          The temporal relation used in the temporal query.
 ITimeReference getTimeReference()
          Defines data time reference.
 String getWhereClause()
          The where clause for the filter.
 int hashCode()
          the hashcode for this object
 void interfaceSupportsErrorInfo(GUID riid)
          interfaceSupportsErrorInfo
 void isDirty()
          isDirty
 boolean isEqual(IClone other)
          Indicates if the receiver and other have the same properties.
 boolean isFilterOwnsGeometry()
          Indicates whether the filter owns the query geometry.
 boolean isIdentical(IClone other)
          Indicates if the receiver and other are the same object.
 boolean isSupportedAtVersion(int docVersion)
          Is this object valid at the given document version.
 void load(IStream pstm)
          load
 void readExternal(ObjectInput in)
           
 void save(IStream pstm, int fClearDirty)
          save
 void serialize(IXMLSerializeData data)
          Serializes an object to XML.
 void setEndingDate(Object pVal)
          Indicates the latest date included in the query.
 void setFilterDefsByRef(IFilterDefs filters)
          The filter definitions specified for this query filter.
 void setGeometryByRef(IGeometry geometry)
          The query geometry used to filter results.
 void setGeometryExByRef(IGeometry geometry, boolean rhs2)
          The query geometry used to filter results.
 void setGeometryField(String geomField)
          The name of the Geometry field to which the filter applies.
 void setOutputSpatialReferenceByRef(String fieldName, ISpatialReference outputSpatialReference)
          The spatial reference in which to output geometry for a given field.
 void setPostfixClause(String clause)
          A clause that will be appended to the SELECT statement, following the where clause.
 void setRelativeTimeOperator(ITemporalOperator pVal)
          The object that contains a relative time to offset the temporal values.
 void setSearchOrder(int order)
          The search order used by the filter.
 void setSpatialRel(int spatialRel)
          The spatial relationship checked by the filter.
 void setSpatialRelDescription(String spatialRelDescription)
          The array elements which describe the spatial relation between the query geometry and the requested geometries.
 void setSpatialResolution(double resolution)
          The spatial resolution in which to output geometry.
 void setStartingDate(Object pVal)
          Indicates the earliest date included in the query.
 void setSubFields(String subFields)
          The comma delimited list of field names for the filter.
 void setTemporalConversion(int pVal)
          The temporal conversion mode to use (if any) by the temporal query.
 void setTemporalOrder(int pVal)
          Defines order in which temporal records are sorted.
 void setTemporalRelationship(int pVal)
          The temporal relation used in the temporal query.
 void setTimeReferenceByRef(ITimeReference timeReference)
          Defines data time reference.
 void setWhereClause(String whereClause)
          The where clause for the filter.
 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

TemporalQueryFilter

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

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

TemporalQueryFilter

public TemporalQueryFilter(Object obj)
                    throws IOException
Construct a TemporalQueryFilter using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to TemporalQueryFilter.

Parameters:
obj - an object returned from ArcGIS Engine or Server
Throws:
IOException - if there are interop problems TemporalQueryFilter theTemporalQueryFilter = (TemporalQueryFilter) obj;
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

getTemporalOrder

public int getTemporalOrder()
                     throws IOException,
                            AutomationException
Defines order in which temporal records are sorted.

Product Availability

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

Specified by:
getTemporalOrder in interface ITemporalQueryFilter
Returns:
A com.esri.arcgis.geodatabaseextensions.enumTemporalOrder constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setTemporalOrder

public void setTemporalOrder(int pVal)
                      throws IOException,
                             AutomationException
Defines order in which temporal records are sorted.

Product Availability

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

Specified by:
setTemporalOrder in interface ITemporalQueryFilter
Parameters:
pVal - A com.esri.arcgis.geodatabaseextensions.enumTemporalOrder constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTemporalRelationship

public int getTemporalRelationship()
                            throws IOException,
                                   AutomationException
The temporal relation used in the temporal query.

Product Availability

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

Specified by:
getTemporalRelationship in interface ITemporalQueryFilter
Returns:
A com.esri.arcgis.geodatabaseextensions.enumTemporalRelation constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setTemporalRelationship

public void setTemporalRelationship(int pVal)
                             throws IOException,
                                    AutomationException
The temporal relation used in the temporal query.

Product Availability

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

Specified by:
setTemporalRelationship in interface ITemporalQueryFilter
Parameters:
pVal - A com.esri.arcgis.geodatabaseextensions.enumTemporalRelation constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getStartingDate

public Object getStartingDate()
                       throws IOException,
                              AutomationException
Indicates the earliest date included in the query.

Product Availability

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

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

setStartingDate

public void setStartingDate(Object pVal)
                     throws IOException,
                            AutomationException
Indicates the earliest date included in the query.

Product Availability

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

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

getEndingDate

public Object getEndingDate()
                     throws IOException,
                            AutomationException
Indicates the latest date included in the query.

Product Availability

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

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

setEndingDate

public void setEndingDate(Object pVal)
                   throws IOException,
                          AutomationException
Indicates the latest date included in the query.

Product Availability

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

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

getTemporalConversion

public int getTemporalConversion()
                          throws IOException,
                                 AutomationException
The temporal conversion mode to use (if any) by the temporal query.

Product Availability

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

Specified by:
getTemporalConversion in interface ITemporalQueryFilter
Returns:
A com.esri.arcgis.geodatabaseextensions.enumTemporalConversion constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setTemporalConversion

public void setTemporalConversion(int pVal)
                           throws IOException,
                                  AutomationException
The temporal conversion mode to use (if any) by the temporal query.

Product Availability

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

Specified by:
setTemporalConversion in interface ITemporalQueryFilter
Parameters:
pVal - A com.esri.arcgis.geodatabaseextensions.enumTemporalConversion constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRelativeTimeOperator

public ITemporalOperator getRelativeTimeOperator()
                                          throws IOException,
                                                 AutomationException
The object that contains a relative time to offset the temporal values.

Product Availability

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

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

setRelativeTimeOperator

public void setRelativeTimeOperator(ITemporalOperator pVal)
                             throws IOException,
                                    AutomationException
The object that contains a relative time to offset the temporal values.

Product Availability

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

Specified by:
setRelativeTimeOperator in interface ITemporalQueryFilter
Parameters:
pVal - A reference to a com.esri.arcgis.geodatabaseextensions.ITemporalOperator (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getTimeReference

public ITimeReference getTimeReference()
                                throws IOException,
                                       AutomationException
Defines data time reference.

Product Availability

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

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

setTimeReferenceByRef

public void setTimeReferenceByRef(ITimeReference timeReference)
                           throws IOException,
                                  AutomationException
Defines data time reference.

Product Availability

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

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

getSearchOrder

public int getSearchOrder()
                   throws IOException,
                          AutomationException
The search order used by the filter.

Description

SearchOrder gets the order in which spatial searches are applied by the RDBMS (ArcSDE). This property only affects ArcSDE Geodatabase data. It has no effect on Personal or File Geodatabase, Coverage or Shapefile data.

Remarks

SearchOrder gets the order in which spatial searches are applied by the RDBMS (ArcSDE). The spatial component of the search should generally be applied before the attribute component. The more spatially restrictive of the two should be used. In the following query, "Find all wells with particulate counts between 1000 and 1200 in within 5 miles of a school", the esriSearchOrderAttribute enumerator is more effective. If the filter geometry is the outline of the city of Modesto, California and the attribute query is "street_name = 'Main St.'" then esriSearchOrderSpatial should be used, as there are a large number of "Main St." records at a national level.

Please note that esriSearchOrderSpatial is the default option. The following esriSearchOrder enumeration values are used to set the search order:

esriSearchOrderAttribute

Sets the search order to attribute first.

esriSearchOrderSpatial

Sets the search order to spatial first.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSearchOrder in interface ISpatialFilter
Returns:
A com.esri.arcgis.geodatabase.esriSearchOrder constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSearchOrder

public void setSearchOrder(int order)
                    throws IOException,
                           AutomationException
The search order used by the filter.

Description

SearchOrder

Sets the order in which spatial searches are applied by the RDBMS (ArcSDE).

Remarks

SearchOrder

Sets the order in which spatial searches are applied by the RDBMS (ArcSDE). The spatial component of the search should generally be applied before the attribute component. The more spatially restrictive of the two should be used. In the following query, "Find all wells with particulate counts between 1000 and 1200 in within 5 miles of a school", the esriSearchOrderAttribute enumerator is more effective. If the filter geometry is the outline of the city of Modesto, California and the attribute query is "street_name = 'Main St.'" then esriSearchOrderSpatial should be used, as there are a large number of "Main St." records at a national level.

NOTE: esriSearchOrderSpatial is the default.

The following esriSearchOrder enumeration values are used to set the search order:

esriSearchOrderAttribute

Sets the search order to attribute first.

esriSearchOrderSpatial

Sets the search order to spatial first.

Example (VB6):

pSpatialFiler.SearchOrder = esriSearchOrderAttribute






Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setSearchOrder in interface ISpatialFilter
Parameters:
order - A com.esri.arcgis.geodatabase.esriSearchOrder constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSpatialRel

public int getSpatialRel()
                  throws IOException,
                         AutomationException
The spatial relationship checked by the filter.

Description

Tolerances

Most spatial relationships are defined by the intersection of boundaries, interior and exterior. All shapes have an interior. Lines and polygons have a boundary. Most spatial relations use a tolerance when examining the spatial relationship between two features. In most cases this tolerance is the XY tolerance of the search feature. All geometries within the tolerance are seen as intersecting. In the overlaps case the tolerance sets the minimum overlap. Geometries that overlap less than the tolerance will not be seen as overlapping.

Tolerance

Relationships that use the XY tolerance:

esriSpatialRelIntersects
esriSpatialRelEnvelopeIntersects
esriSpatialRelTouches
esriSpatialRelOverlaps
esriSpatialRelCrosses
esriSpatialRelWithin
esriSpatialRelContains

The esriSpatialRelRelation uses the XY resolution. Usually ten times smaller than the XY tolerance.

esriSpatialRelIndexIntersects does not use a tolerance.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSpatialRel in interface ISpatialFilter
Returns:
A com.esri.arcgis.geodatabase.esriSpatialRelEnum constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSpatialRel

public void setSpatialRel(int spatialRel)
                   throws IOException,
                          AutomationException
The spatial relationship checked by the filter.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setSpatialRel in interface ISpatialFilter
Parameters:
spatialRel - A com.esri.arcgis.geodatabase.esriSpatialRelEnum constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getGeometry

public IGeometry getGeometry()
                      throws IOException,
                             AutomationException
The query geometry used to filter results.

Description

Only high-level geometries, envelopes and geometry bags can be used. High-level geometries are polygons, polylines, points, and multipoints. Low-level geometries including paths, rings, arcs and curves, and lines can not be used. To test whether a geometry is applicable, see if it implements the IRelationalOperator interface; if it does, it can be used.

Remarks

If a geometry bag is being used as the filter's query geometry, a spatial index should be created for the bag prior to any evaluation using the filter. This can be done by casting the geometry bag to the ISpatialIndex interface, setting the AllowIndexing property to true, and calling the Invalidate method.

Note that at ArcGIS 9.3 and later, setting this property to null will cause an error.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

setGeometryByRef

public void setGeometryByRef(IGeometry geometry)
                      throws IOException,
                             AutomationException
The query geometry used to filter results.

Description

Only high-level geometries, envelopes and geometry bags can be used. High-level geometries are polygons, polylines, points, and multipoints. Low-level geometries including paths, rings, arcs and curves, and lines can not be used. To test whether a geometry is applicable, see if it implements the IRelationalOperator interface; if it does, it can be used.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setGeometryByRef in interface ISpatialFilter
Parameters:
geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setGeometryExByRef

public void setGeometryExByRef(IGeometry geometry,
                               boolean rhs2)
                        throws IOException,
                               AutomationException
The query geometry used to filter results.

Description

Only high-level geometries, envelopes and geometry bags can be used. High-level geometries are polygons, polylines, points, and multipoints. Low-level geometries including paths, rings, arcs and curves, and lines can not be used. To test whether a geometry is applicable, see if it implements the IRelationalOperator interface; if it does, it can be used.

Remarks

The boolean parameter represents the FilterOwnsGeometry property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setGeometryExByRef in interface ISpatialFilter
Parameters:
geometry - A reference to a com.esri.arcgis.geometry.IGeometry (in)
rhs2 - The rhs2 (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isFilterOwnsGeometry

public boolean isFilterOwnsGeometry()
                             throws IOException,
                                    AutomationException
Indicates whether the filter owns the query geometry.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isFilterOwnsGeometry in interface ISpatialFilter
Returns:
The spatialFilterOwnsGeometry
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getGeometryField

public String getGeometryField()
                        throws IOException,
                               AutomationException
The name of the Geometry field to which the filter applies.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getGeometryField in interface ISpatialFilter
Returns:
The geomField
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setGeometryField

public void setGeometryField(String geomField)
                      throws IOException,
                             AutomationException
The name of the Geometry field to which the filter applies.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getSpatialRelDescription

public String getSpatialRelDescription()
                                throws IOException,
                                       AutomationException
The array elements which describe the spatial relation between the query geometry and the requested geometries. There are 9 chars in this string which can be either 'F', 'T' or '*'; e.g., TT*FFT***' represents CONTAIN.

Description

A nine character string containing describing the spatial relationships to be tested by the spatial filter. Required when setting the SpatialRel property to use the esriSpatialRelRelation enumerator.

Remarks

The SpatialRelDescription allows the comparison of any spatial relationship between two geometries. A spatial relationship is defined by the intersections between the boundary, interior, and exterior of the query geometry and the requested geometry.

All of the spatial relationships defined by the esriSpatialRelEnum enumeration can be duplicated using this property.


Interior:
The interior of a shape is defined as the entire shape minus its boundary. All shapes have interior.

Boundary:
Linear and area shapes have boundaries, but point shapes do not. The boundary of linear shapes consists of the end points of all linear parts. The boundary of area shapes consists of the linear boundary of the polygon shell(s).

Exterior:
The area outside a shape. All shapes have an exterior.

Each element for the first shape, the query geometry, may be tested against each element of the second shape, the requested geometry, giving nine possible spatial intersections as listed in the table below:

Query Geometry Requested Geometry
1 interior interior
2 interior boundary
3 interior exterior
4 boundary interior
5 boundary boundary
6 boundary exterior
7 exterior interior
8 exterior boundary
9 exterior exterior


The nine-characters string expected by ISpatialFilter::SpatialRelDescription, is used to specify whether the intersection of each of the elements in the array is true (T), false (F), or not tested (*).

For instance, in 'FFFTTT***', relationships 1-3 must be false, relationships 4-6 must be true, and relationships 7-9 are not tested.

Note that any two shapes' exteriors always intersect.

Example Strings

Shares a boundary: '****T***'

Shares a boundary and interiors intersect: 'T***T****'

Shares a boundary and interiors do not intersect: 'F***T****'

Does not touch the boundary and interiors intersect: 'T***F****'

Approximate esriSpatialRelEnum SpatialRelDescription Strings
Relation Query Geometry Requested Geometry String
Contains Line Line TT*FFT***
Contains Point Line TT*FFT***
Contains Point Point T********
Contains Line Poly TT*FFT***
Contains Poly Poly TT*FFT***
Crosses Line Line TF*FF****
Crosses Poly Line TT**F****
Crosses Line Poly TT**T****
Overlaps Line Line TT*T*****
Overlaps Point Point T********
Overlaps Poly Poly TT*T*****
Touch Line Line FF*FT****
Touch Poly Line FF*FT****
Touch Line Poly FF*FT****
Touch Poly Poly FF*FT****
Within Line Line TF**F****
Within Point Line T********
Within Point Point T********
Within Line Poly TF**F****
Within Poly Poly TF**F****



Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSpatialRelDescription in interface ISpatialFilter
Returns:
The spatialRelDescription
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSpatialRelDescription

public void setSpatialRelDescription(String spatialRelDescription)
                              throws IOException,
                                     AutomationException
The array elements which describe the spatial relation between the query geometry and the requested geometries. There are 9 chars in this string which can be either 'F', 'T' or '*'; e.g., TT*FFT***' represents CONTAIN.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getSubFields

public String getSubFields()
                    throws IOException,
                           AutomationException
The comma delimited list of field names for the filter.

Description

You can use the SubFields property to improve performance when using query filters. The performance gain comes from just fetching the field values that you require rather than all the data for each row. The default value for SubFields is "*", which indicates that all field values will be returned. Setting it back to this original (default) "*" can be done either by setting it to "*" or to "".

The SubFields property should be a comma-delimited list of the columns that are required. For example, to retrieve two fields named "OBJECTID" and "NAME", the property should be set to "OBJECTID, NAME" (the space is optional).

It isn’t necessary to set the subfields when the query filter is used in a context in which no attribute values are fetched, for example, when selecting features.

Remarks

When accessing rows from a subset of data defined by a query filter, all the fields will be present, but just those specified by SubFields will be populated with values. This ensures that the field index positions for an object remain constant no matter how it was hydrated.

When editing data, always use "*" for the SubFields property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSubFields in interface IQueryFilter
Returns:
The subFields
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSubFields

public void setSubFields(String subFields)
                  throws IOException,
                         AutomationException
The comma delimited list of field names for the filter.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

addField

public void addField(String subField)
              throws IOException,
                     AutomationException
Appends a single field name to the list of sub-fields.

Remarks

The AddField method can be used to add a field to the SubFields list before the query is executed. Adding a field will clear the default "*" value from the SubFields. Setting it back to this original "*" can be done either by setting Subfields to "*" or to "".

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getWhereClause

public String getWhereClause()
                      throws IOException,
                             AutomationException
The where clause for the filter.

Description

The WhereClause property allows you to specify an expression which will constrain the features returned from the QueryFilter. For example, you can use the WhereClause property to select all the polygons with an area greater than 1,500 square units: "AREA" > 1500.

The expression specified with the WhereClause property is a SQL query. The syntax of the query differs depending on the data source you are using, as it is in the native format of the database or data source. An application can use the ISQLSyntax interface on a Workspace to determine information about the SQL syntax used, such as the delimiting character used in qualifying table and field names and the identifier quote character.

Field names

- If you are querying data in a file geodatabase, shapefile, dBase table, coverage, INFO table, then field names are enclosed in double quotes:
"AREA"

- If you are querying data in a personal geodatabase then field names are enclosed in square brackets:
[AREA]
- If you are querying data in an ArcSDE geodatabase or an ArcIMS image service or feature service, then fields are not enclosed:
AREA
- If you are querying data in a worksheet in an Excel file (.xls file) or a text file (.txt file), fields are delimited in single quotes 'AREA' unless you are working in the Select By Attributes dialog launched from the table window, in which case square brackets [AREA] are used.

Use ISQLSyntax::GetSpecialCharacter to return the delimited identifier prefix and suffix for the data source.

Strings

Strings must always be enclosed within single quotes. For example:

"STATE_NAME" = 'California'

Personal geodatabases stored in Access are case insensitive to field values, whereas ArcSDE, File and shapefiles are case sensitive. To make a case insensitive search in other data formats, you can use a SQL function to convert all values to the same case. For file-based data sources, use either the UPPER or LOWER function.

For example, given a field value of "Florida", a WhereClause of "State_name = 'florida'" will return one USA state when run against a data in a personal geodatabase, but none with and shapefiles and ArcSDE. A WhereClause of "State_name = 'Florida'" will return one feature in all cases.

For example, the following expression will select customers whose last name is stored as either Jones or JONES:

UPPER("LAST_NAME") = 'JONES'

Other data sources have similar functions. Personal geodatabases, for example, have functions named UCASE and LCASE that perform the same function.

Use the LIKE operator (instead of the = operator) to build a partial string search. For example, this expression would select Mississippi and Missouri among the USA state names:

"STATE_NAME" LIKE 'Miss%'

Use ISQLSyntax::GetSpecialCharacter to return the delimited identifier prefix and suffix for the data source.

Wildcard Characters

A wildcard character is a special symbol that stands for one or more characters.

For any file-based data, '%' means that anything is acceptable in its place: one character, a hundred characters, or no character. Alternatively, if you want to search with a wildcard that represents one character, use '_'.

For example, this expression would select any name starting with the letters Cath, such as Cathy, Catherine, and Catherine Smith:

"NAME" LIKE 'Cath%'

But this expression would find Catherine Smith and Katherine Smith:
"OWNER_NAME" LIKE '_atherine smith'

The wildcards you use to query personal geodatabases are '*' for any number of characters and '?' for one character.

Use ISQLSyntax::GetSpecialCharacter to return the wildcard specific for the data source being queried.

NOTE: If you use a wildcard character in a string with the = operator, the character is treated as part of the string, not as a wildcard.

With a joined table, use wildcards appropriate for the side of the join that you are querying. If the query only applies to fields in the target table (the left-side table), use the target table wildcards. If the query only applies to fields in the join table (the right-side table), use the join table wildcards. If the query involves fields from both sides of the join, use the '%' and '_' wildcards.

For example, if you join a dbf file (the join table) to a personal geodatabase feature class (the target table):

1) Use * for queries that only involve personal geodatabase fields.

2) Use % for queries that only involve dbf columns.

3) Use % for queries involving columns from both sides of the table.

The NULL keyword

Null values are supported in fields for geodatabases and for date fields in shapefiles/dBASE tables and coverages/INFO tables.

The Distinct keyword

The Distinct keyword is not supported by file geodatabases. The recommended workaround is to use the IDataStatistics::UniqueValues method to return the distinct values for a field.

Querying numbers

You can query numbers using the equal (=), not equal (<>), greater than (>), less than (<), greater than or equal (>=), and less than or equal (<=) operators.

"POPULATION96" >= 5000

Querying dates

The syntax required for querying dates depends on the data type. ArcMap will automatically write the proper syntax for you when you double-click a date value in the Unique Values list. See the SQL reference mentioned above for more about querying dates.

Reference

For more information on using SQL in a query filter, see the ArcGIS web help article, SQL reference.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getWhereClause in interface IQueryFilter
Returns:
The whereClause
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setWhereClause

public void setWhereClause(String whereClause)
                    throws IOException,
                           AutomationException
The where clause for the filter.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getOutputSpatialReference

public ISpatialReference getOutputSpatialReference(String fieldName)
                                            throws IOException,
                                                   AutomationException
The spatial reference in which to output geometry for a given field.

Product Availability

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

Specified by:
getOutputSpatialReference in interface IQueryFilter
Parameters:
fieldName - The fieldName (in)
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.

setOutputSpatialReferenceByRef

public void setOutputSpatialReferenceByRef(String fieldName,
                                           ISpatialReference outputSpatialReference)
                                    throws IOException,
                                           AutomationException
The spatial reference in which to output geometry for a given field.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setOutputSpatialReferenceByRef in interface IQueryFilter
Parameters:
fieldName - The fieldName (in)
outputSpatialReference - 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.

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.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws IOException,
                                       AutomationException
interfaceSupportsErrorInfo

Description

Indicates whether the interface supports IErrorInfo.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
interfaceSupportsErrorInfo in interface ISupportErrorInfo
Parameters:
riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)
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.

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.

getSpatialResolution

public double getSpatialResolution()
                            throws IOException,
                                   AutomationException
The spatial resolution in which to output geometry.

Description

The SpatialResolution method provides generalization of shapes returned by a filter. The generalization is performed on the server to minimize network travel. A zero value is default and will result in no generalization. The higher the value, the greater the generalization performed. The value is specified in feature units and generally should be roughly the size of one display pixel (measured in feature units).

This method is only supported on ArcGIS feature service and ArcIMS data sources. It will be ignored on all other data sources.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSpatialResolution in interface IQueryFilter2
Returns:
The resolution
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSpatialResolution

public void setSpatialResolution(double resolution)
                          throws IOException,
                                 AutomationException
The spatial resolution in which to output geometry.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getPostfixClause

public String getPostfixClause()
                        throws IOException,
                               AutomationException
A clause that will be appended to the SELECT statement, following the where clause. Most commonly used for clauses like ORDER BY.

Remarks

The PostfixClause property allows for a postfix clause to be added to a query filter. The PostfixClause property is a string property. It can be used to specify an ORDER BY clause for the query. Historically, this clause has not been supported due to issues with placement in the SQL generated for spatial and/or versioned queries. This property ensures proper placement of the clause in the SQL generated by the system.

Product Availability

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

Specified by:
getPostfixClause in interface IQueryFilterDefinition
Returns:
The clause
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setPostfixClause

public void setPostfixClause(String clause)
                      throws IOException,
                             AutomationException
A clause that will be appended to the SELECT statement, following the where clause. Most commonly used for clauses like ORDER BY.

Product Availability

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

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

getFilterDefs

public IFilterDefs getFilterDefs()
                          throws IOException,
                                 AutomationException
The filter definitions specified for this query filter.

Remarks

The FilterDefs property contains the set of FilterDefs objects that will be applied to the query.

Product Availability

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

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

setFilterDefsByRef

public void setFilterDefsByRef(IFilterDefs filters)
                        throws IOException,
                               AutomationException
The filter definitions specified for this query filter.

Product Availability

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

Specified by:
setFilterDefsByRef in interface IQueryFilterDefinition
Parameters:
filters - A reference to a com.esri.arcgis.geodatabase.IFilterDefs (in)
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.

isSupportedAtVersion

public boolean isSupportedAtVersion(int docVersion)
                             throws IOException,
                                    AutomationException
Is this object valid at the given document version.

Remarks

Use IsSupportedAtVersion to identify if a particular object should be saved to the ObjectStream. This result is based on the esriArcGISVersion enumeration. In some instances, if the object is not supported at a particular ArcGIS version, the object may support conversion to another similar object; use IDocumentVersionSupportGEN::ConvertToSupportedObject to accomplish this.

Product Availability

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

Specified by:
isSupportedAtVersion in interface IDocumentVersionSupportGEN
Parameters:
docVersion - A com.esri.arcgis.system.esriArcGISVersion constant (in)
Returns:
The supported
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

convertToSupportedObject

public Object convertToSupportedObject(int docVersion)
                                throws IOException,
                                       AutomationException
Convert the object to another object that is supported.

Remarks

This method should be used when IDocumentVersionSupportGEN::IsSupportedAtVersion returns FALSE. Calling ConvertToSupportedObject will return an IUnknown pointer to a relevant object supported at the particular ArcGIS version. Not all objects will return a supported object; in these cases a null pointer will be returned.

Product Availability

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

Specified by:
convertToSupportedObject in interface IDocumentVersionSupportGEN
Parameters:
docVersion - A com.esri.arcgis.system.esriArcGISVersion constant (in)
Returns:
A Variant
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