com.esri.arcgis.geodatabase
Interface ISpatialFilter

All Superinterfaces:

IQueryFilter, java.io.Serializable

All Known Implementing Classes:

ISpatialFilterProxy, SpatialFilter, TemporalQueryFilter

public interface ISpatialFilter

extends IQueryFilter, java.io.Serializable

Provides access to members that return and modify the type of spatial relationship that the filter will use.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Description

ISpatialFilter is a QueryFilter that includes both spatial and attribute constraints. Therefore, a SpatialFilter can be used to restrict the set of features retrieved from a feature class using both spatial and attribute restrictions. ISpatialFilter inherits from IQueryFilter so you can optionally specify a string defining a where clause, include a list of columns to be retrieved or specify the spatial reference in which to output the geometry of the resulting features. See the IQueryFilter interface for help on the inherited methods and properties.

The most common ways to perform a spatial query using a spatial filter is to create the spatial filter using this interface and use it as a parameter for IFeatureClass::Search, IFeatureClass::Select or similar methods on feature layers, selection sets, etc.

The Geometry and SpatialRel properties are required.

Geometry is the source geometry in relation to which the spatial selection will be performed. GeometryField is a string corresponding to the name of the field containing the geometries to be compared to the source geometry. Finally the spatial relationship is specified with the SpatialRel property passing it an esriSpatialRelEnum .

A SearchOrder can be specified using an esriSearchOrder. When an attribute query is specified it will specify which of the attritute or spatial part of the query is executed first. A judicious choice may significantly improve the performances. This is only available with SDE datasources.

The SpatialRelDescription is a string containing specific codes that can be used instead of the SpatialRel property to define extra spatial relationships. In this case the SpatialRel parameter must be set to esriSpatialRelRelation. See the help on the SpatialRelDescription topic for detail on the strings to use.

The esriGeometry provides other ways to perform a spatial selection. See for instance the example associated with ITopologicalOperator that performs a spatial selection on polylines that share a line segment.

Remarks

Note on ORDER BY and returning sorted data: To add ORDER BY and GROUP BY clauses to the attribute query the WhereClause property can be used prior to evaluating the query

See Also:

IQueryDef, IQueryFilter, Filter

Method Summary

IGeometry	getGeometry() The query geometry used to filter results.
java.lang.String	getGeometryField() The name of the Geometry field to which the filter applies.
int	getSearchOrder() The search order used by the filter.
int	getSpatialRel() The spatial relationship checked by the filter.
java.lang.String	getSpatialRelDescription() The array elements which describe the spatial relation between the query geometry and the requested geometries.
boolean	isFilterOwnsGeometry() Indicates whether the filter owns the query geometry.
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(java.lang.String geomField) The name of the Geometry field to which the filter applies.
void	setSearchOrder(int order) The search order used by the filter.
void	setSpatialRel(int spatialRel) The spatial relationship checked by the filter.
void	setSpatialRelDescription(java.lang.String spatialRelDescription) The array elements which describe the spatial relation between the query geometry and the requested geometries.

Methods inherited from interface com.esri.arcgis.geodatabase.IQueryFilter

addField, getOutputSpatialReference, getSubFields, getWhereClause, setOutputSpatialReferenceByRef, setSubFields, setWhereClause

Method Detail

getSearchOrder

public int getSearchOrder()
                   throws java.io.IOException,
                          AutomationException

The search order used by the filter.

Supported Platforms

Windows, Solaris, Linux

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 enumerators are used to set the search order.

esriSearchOrderAttribute

Sets the search order to attribute first.

esriSearchOrderSpatial

Sets the search order to spatial first.

Example:

  pSpatialFiler.SearchOrder = esriSearchOrderAttribute

Returns:

A com.esri.arcgis.geodatabase.esriSearchOrder constant

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSearchOrder

public void setSearchOrder(int order)
                    throws java.io.IOException,
                           AutomationException

The search order used by the filter.

Supported Platforms

Windows, Solaris, Linux

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 enumerators are used to set the search order.

esriSearchOrderAttribute

Sets the search order to attribute first.

esriSearchOrderSpatial

Sets the search order to spatial first.

Example:

pSpatialFiler.SearchOrder = esriSearchOrderAttribute

Parameters:

order - A com.esri.arcgis.geodatabase.esriSearchOrder constant (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSpatialRel

public int getSpatialRel()
                  throws java.io.IOException,
                         AutomationException

The spatial relationship checked by the filter.

Supported Platforms

Windows, Solaris, Linux

Returns:

A com.esri.arcgis.geodatabase.esriSpatialRelEnum constant

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSpatialRel

public void setSpatialRel(int spatialRel)
                   throws java.io.IOException,
                          AutomationException

The spatial relationship checked by the filter.

Supported Platforms

Windows, Solaris, Linux

Parameters:

spatialRel - A com.esri.arcgis.geodatabase.esriSpatialRelEnum constant (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGeometry

public IGeometry getGeometry()
                      throws java.io.IOException,
                             AutomationException

The query geometry used to filter results.

Supported Platforms

Windows, Solaris, Linux

Description

Only high-level geometries 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.

Returns:

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

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setGeometryByRef

public void setGeometryByRef(IGeometry geometry)
                      throws java.io.IOException,
                             AutomationException

The query geometry used to filter results.

Parameters:

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

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setGeometryExByRef

public void setGeometryExByRef(IGeometry geometry,
                               boolean rhs2)
                        throws java.io.IOException,
                               AutomationException

The query geometry used to filter results.

Parameters:

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

rhs2 - The rhs2 (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isFilterOwnsGeometry

public boolean isFilterOwnsGeometry()
                             throws java.io.IOException,
                                    AutomationException

Indicates whether the filter owns the query geometry.

Supported Platforms

Windows, Solaris, Linux

Returns:

The spatialFilterOwnsGeometry

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getGeometryField

public java.lang.String getGeometryField()
                                  throws java.io.IOException,
                                         AutomationException

The name of the Geometry field to which the filter applies.

Supported Platforms

Windows, Solaris, Linux

Returns:

The geomField

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setGeometryField

public void setGeometryField(java.lang.String geomField)
                      throws java.io.IOException,
                             AutomationException

The name of the Geometry field to which the filter applies.

Supported Platforms

Windows, Solaris, Linux

Parameters:

geomField - The geomField (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSpatialRelDescription

public java.lang.String getSpatialRelDescription()
                                          throws java.io.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.

Supported Platforms

Windows, Solaris, Linux

Description

SpatialRelDescription
A nine characters 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 and all possible spatial intersections between two shapes. The intersection of each shapes boundary, interior, and exterior can be tested to allow the confirmation or various spatial relationships. All other spatial enumerators can be duplicated using this enumerator.

Shape relationships are defined by the intersection of their boundary, interior, and exterior.

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 boundary, 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****'

Returns:

The spatialRelDescription

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSpatialRelDescription

public void setSpatialRelDescription(java.lang.String spatialRelDescription)
                              throws java.io.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.

Supported Platforms

Windows, Solaris, Linux

Parameters:

spatialRelDescription - The spatialRelDescription (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.