com.esri.arcgis.geodatabase
Class RelQueryCursor

java.lang.Object
  com.esri.arcgis.geodatabase.RelQueryCursor

All Implemented Interfaces:

ICursor, IFeatureCursor, com.esri.arcgis.interop.RemoteObjRef, Serializable

public class RelQueryCursor
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, ICursor, IFeatureCursor

A cursor that is opened from a RelQueryTable.

Remarks

A RelQueryCursor is a tool that references the rows in a RelQueryTable. Each row retuned by the cursor includes fields from both the source and destination tables with the source fields on the left. Each row from the source and destination tables are matched according to the join fields to create a single row.

A RelQueryCursor is created when you open a cursor on a RelQueryTable. You can use methods such as Search from ITable and IFeatureClass to open the cursor. Since it inherits from Cursor, it implements ICursor and will implement IFeatureCursor if the RelQueryTable has geometry.

RelQueryCursors are read-only, therefore performing edits using the IRow::Delete and IRow::Store methods is not supported. Also, trying to open an insert or an update cursor will result in an error, since there is no insert or update RelQueryCursor.

The following is a review of the inheritied interfaces and describes which properties and methods behave differently or are not supported with RelQueryCursor.

ICursor

The table below describes how the methods and properties from ICursor are implemented by a RelQueryCursor:

Member	Behavior with a MemoryRelationshipClass
Fields	Returns the fields of RelQueryTable.
DeleteRow	Method is not supported since update cursors are not supported. An error will be returned if you try to use this method.
FindField	Returns the index of the field with the given name. If the field does not exist, a -1 is returned. It is good practice to provide a fully qualified field name (tablename.fieldname) with this method. If it is not fully qualified, it may not be found in the RelQueryTable.
Flush	Method is not supported since update and insert cursors are not supported. An error will be returned if you try to use this method.
InsertRow	Method is not supported since update cursors are not supported. An error will be returned if you try to use this method.
NextRow	Moves the cursor to the next row and returns the Row object at that position.
UpdateRow	Method is not supported since update cursors are not supported. An error will be returned if you try to use this method.

IFeatureCursor

The IFeatureCursor interface provides access to a set of features in a RelQueryTable and operates the same way as ICursor. The information provided in the above table for ICursor can also be applied to IFeatureCursor. As with ICursor, the InsertFeature, UpdateFeature, DeleteFeature, and Flush methods are not supported by RelQueryTable.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

See Also:

Serialized Form

Constructor Summary

RelQueryCursor(Object obj)
Construct a RelQueryCursor using a reference to such an object returned from ArcGIS Engine or Server.

Method Summary

void	deleteFeature() Delete the existing Feature in the database corresponding to the current position of the cursor.
void	deleteRow() Delete the existing Row in the database corresponding to the current position of the cursor.
boolean	equals(Object o) Compare this object with another
int	findField(String name) The index of the field with the specified name.
void	flush() Flush any outstanding buffered writes to the database.
IFields	getFields() The Fields Collection for this cursor.
int	hashCode() the hashcode for this object
Object	insertFeature(IFeatureBuffer buffer) Insert a new Feature into the database using the property values in the input buffer.
Object	insertRow(IRowBuffer buffer) Insert a new Row into the database using the property values in the input buffer.
IFeature	nextFeature() Advance the position of the cursor by one and return the Feature object at that position.
IRow	nextRow() Advance the position of the cursor by one and return the Row object at that position.
void	updateFeature(IFeature object) Update the existing Feature in the database corresponding to the current position of the cursor.
void	updateRow(IRow row) Update the existing Row in the database corresponding to the current position of the cursor.

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

RelQueryCursor

public RelQueryCursor(Object obj)
               throws IOException

Construct a RelQueryCursor using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to RelQueryCursor.
Casting to this class from the return value of a method will not work, as this class represents an abstract class in ArcObjects.
*
RelQueryCursor o = (RelQueryCursor)obj; // will not work

RelQueryCursor o = new RelQueryCursor(obj); // Use this constructor instead
* @param obj an object returned from ArcGIS Engine or Server

Throws:

IOException - if there are interop problems RelQueryCursor theRelQueryCursor = (RelQueryCursor) obj;

Method Detail

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

findField

public int findField(String name)
              throws IOException,
                     AutomationException

The index of the field with the specified name.

Remarks

If the specified field cannot be found, this method returns a value of -1.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

findField in interface ICursor

Specified by:

findField in interface IFeatureCursor

Parameters:

name - The name (in)

Returns:

The fieldIndex

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getFields

public IFields getFields()
                  throws IOException,
                         AutomationException

The Fields Collection for this cursor.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getFields in interface ICursor

Specified by:

getFields in interface IFeatureCursor

Returns:

A reference to a com.esri.arcgis.geodatabase.IFields

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

nextRow

public IRow nextRow()
             throws IOException,
                    AutomationException

Advance the position of the cursor by one and return the Row object at that position.

Remarks

The NextRow method on a search or update cursor returns the next row in the result set to the application. The row object returned is allocated and hydrated by the cursor, and a reference to it is handed to the application. To retrieve all rows in a result set containing N rows, the application must make N calls to NextRow. If no rows remain in the result set, this method returns a null value.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

nextRow in interface ICursor

Returns:

A reference to a com.esri.arcgis.geodatabase.IRow

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

updateRow

public void updateRow(IRow row)
               throws IOException,
                      AutomationException

Update the existing Row in the database corresponding to the current position of the cursor.

Remarks

This method should only be called on update cursors.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

updateRow in interface ICursor

Parameters:

row - A reference to a com.esri.arcgis.geodatabase.IRow (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

deleteRow

public void deleteRow()
               throws IOException,
                      AutomationException

Delete the existing Row in the database corresponding to the current position of the cursor.

Remarks

The cursor must be initialized to a row (with the NextRow method) before this method can be successfully called.

This should only be called on update cursors. To delete a row retrieved from a search cursor, call IRow.Delete on the row itself.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

deleteRow in interface ICursor

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

insertRow

public Object insertRow(IRowBuffer buffer)
                 throws IOException,
                        AutomationException

Insert a new Row into the database using the property values in the input buffer. The object ID of the new Row, if there is one, is returned.

Remarks

This method should only be called on insert cursors.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

insertRow in interface ICursor

Parameters:

buffer - A reference to a com.esri.arcgis.geodatabase.IRowBuffer (in)

Returns:

A Variant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

flush

public void flush()
           throws IOException,
                  AutomationException

Flush any outstanding buffered writes to the database.

Remarks

This method should only be called on insert cursors.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

flush in interface ICursor

Specified by:

flush in interface IFeatureCursor

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

nextFeature

public IFeature nextFeature()
                     throws IOException,
                            AutomationException

Advance the position of the cursor by one and return the Feature object at that position.

Remarks

If you fetch features out of a geodatabase using a cursor (recycling or non recycling), the spatial reference of the feature, as returned by NextFeature, is guaranteed to be in the spatial reference that you specified in the query filter .

No guarantee however is made that the geometry of the feature will continue to remain in this spatial reference. In particular, if you use a non recycling cursor, then the feature you fetch will be shared with other consumers and any one of these may change its spatial reference at any time. It is the developers responsibility to test the spatial reference or the geometry you get from the feature (via IFeature::Shape) if you retrieve the geometry at a later time and rely on its spatial reference being a specified spatial reference.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

nextFeature in interface IFeatureCursor

Returns:

A reference to a com.esri.arcgis.geodatabase.IFeature

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

updateFeature

public void updateFeature(IFeature object)
                   throws IOException,
                          AutomationException

Update the existing Feature in the database corresponding to the current position of the cursor.

Remarks

This method should only be called on update cursors.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

updateFeature in interface IFeatureCursor

Parameters:

object - A reference to a com.esri.arcgis.geodatabase.IFeature (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

deleteFeature

public void deleteFeature()
                   throws IOException,
                          AutomationException

Delete the existing Feature in the database corresponding to the current position of the cursor.

Remarks

The cursor must be initialized to a feature (with the NextFeature() method) before this method can be successfully called.

This should only be called on update cursors. To delete a feature retrieved from a search cursor, call IFeature.Delete on the feature itself.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

deleteFeature in interface IFeatureCursor

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

insertFeature

public Object insertFeature(IFeatureBuffer buffer)
                     throws IOException,
                            AutomationException

Insert a new Feature into the database using the property values in the input buffer. The ID of the new Feature is returned.

Remarks

This method should only be called on insert cursors.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

insertFeature in interface IFeatureCursor

Parameters:

buffer - A reference to a com.esri.arcgis.geodatabase.IFeatureBuffer (in)

Returns:

A Variant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.