com.esri.arcgis.geodatabase
Class QueryFilter

java.lang.Object
  extended by com.esri.arcgis.geodatabase.QueryFilter
All Implemented Interfaces:
IQueryFilter, IQueryFilter2, IQueryFilterDefinition, com.esri.arcgis.interop.RemoteObjRef, IClone, IPersist, IPersistStream, IXMLSerialize, Externalizable, Serializable

public class QueryFilter
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IQueryFilter, IQueryFilter2, IQueryFilterDefinition, IClone, IPersistStream, IXMLSerialize, Externalizable

ESRI Query Filter object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

See Also:
Serialized Form

Constructor Summary
QueryFilter()
          Constructs a QueryFilter using ArcGIS Engine.
QueryFilter(Object obj)
          Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
QueryFilter theQueryFilter = (QueryFilter) obj;
 
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.
 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.
 IFilterDefs getFilterDefs()
          The filter definitions specified for this query filter.
 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 end of the where clause.
 void getSizeMax(_ULARGE_INTEGER[] pcbSize)
          getSizeMax
 double getSpatialResolution()
          The spatial resolution in which to output geometry.
 String getSubFields()
          The comma delimited list of field names for the filter.
 String getWhereClause()
          The where clause for the filter.
 int hashCode()
          the hashcode for this object
 void isDirty()
          isDirty
 boolean isEqual(IClone other)
          Returns TRUE when the receiver and other have the same properties.
 boolean isIdentical(IClone other)
          Returns TRUE when the receiver and other are the same object.
 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 setFilterDefsByRef(IFilterDefs filters)
          The filter definitions specified for this query filter.
 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 end of the where clause.
 void setSpatialResolution(double resolution)
          The spatial resolution in which to output geometry.
 void setSubFields(String subFields)
          The comma delimited list of field names for the filter.
 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

QueryFilter

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

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

QueryFilter

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

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

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

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.

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 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 end of 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.

Please note, file geodatabases do not support the PostFixClause property, and any specifications within the PostFixClause will be ignored.

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 end of 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.

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
Returns TRUE when 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
Returns TRUE when 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.

isDirty

public void isDirty()
             throws IOException,
                    AutomationException
isDirty

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

load

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

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

save

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

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getSizeMax

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

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

getClassID

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

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

serialize

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

deserialize

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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

writeExternal

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

readExternal

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