com.esri.arcgis.geodatabase
Interface IWorkspaceEdit

All Superinterfaces:

Serializable

All Known Subinterfaces:

IWorkspaceEdit2

All Known Implementing Classes:

IWorkspaceEdit2Proxy, IWorkspaceEditProxy, VersionedWorkspace, Workspace

public interface IWorkspaceEdit
extends Serializable

Provides access to members that control Workspace Editing.

Superseded By

IWorkspaceEdit2

Remarks

The IWorkspaceEdit interface allows the application to start and stop edit sessions during which the objects in a geodatabase can be updated. An edit session corresponds to a long transaction. To start a non-versioned edit session against an ArcSDE datasource the IMultiuserWorkspaceEdit interface should be used. In fact, when programmatically editing objects within a ArcSDE database it is recommended that the IMultiuserWorkspaceEdit interface be used. The only data changes an application sees within an edit session are changes that are made by the application. Changes made by other concurrently executing applications (if allowed) are not seen until the edit session is saved or discarded.

When required to insert, update or delete objects, it is strongly recommended to perform the operation using an edit session and within an edit operation. Although (in most cases) these operations can be performed without explicitly starting and stopping an edit operation, the resulting change will be non-deterministic in respect to which state of the database the operation is associated or even the possibility of encountering an error when the change can not be applied to an open state. For these reasons all edits should be performed within an edit operation.

The geodatabase guarantees ‘unique instancing’ of row objects retrieved from the database within an edit session. Any data access call that retrieves a non-recycling object with a particular object ID will return the in memory instance of the object if the object has already been instantiated by the application. Such behavior is needed to ensure application correctness when updating complex object models—for example, models with relationship-based messaging or models with network features where updates to the geometry of a feature affect the geometry of topologically related features.

For this reason all object editing should be done within an edit session. The geodatabase data update APIs (such as IRow::Store, ITable::Update, and ITable::Insert ) will fail if you attempt to use them outside of an edit session on object and feature classes that are marked as requiring an edit session to ensure unique instancing semantics.

The geodatabase does not support nested transactions. When editing in a versioned environment on a SDE geodatabase only one transaction should be open at any one time. This means that if the same connection is used to edit multiple versions it is good practice to call StopEditing on the first edit session prior to calling StartEditing on another version. If another transaction is opened prior to closing the first transaction an open transaction error will be returned to the application. Programmatically this can be avoided by calling IsBeingEdited prior to StartEditing.

Applications should be aware that DDL (data definition language) operations made through ArcObjects geodatabase data access objects (for example, deleting feature dataset or creating a new feature class) use database transactions to ensure integrity of the data dictionary tables and commit the transaction at the end of the operation. Applications should not invoke DDL operations within an application transaction—application transactions should be restricted to DML operations (such as data updates).

The rules for correct object editing on a geodatabase are summarized below:

1. All object editing should be done within an edit session.
2. Group changes into edit operations.
3. Discard all references to row objects retrieved at the edit session boundary (on StartEditing). If references to row objects will be maintained across edit operations then discard all references and refetch objects in response to the Undo, redo and abort edit operation calls made by the application as well as the reconcile call made within an edit session on versioned databases. In the context of ArcMap, these calls are made by the editor which broadcasts corresponding editor events via the IEditorEvents and IEditorEvents2 interfaces. Personal and enterprise geodatabase workspaces support the IWorkspaceEditEvents and the IVersionEvents outbound interfaces and directly broadcast these events.
4. Use non-recycling search cursors to fetch objects that are to be updated (using any of the Search, GetRow, or GetRows methods supported by tables, feature classes and selection sets). Recycling cursors should be used only for drawing and read-only access to object state.
5. Always fetch all properties of the objects to be edited. Query filters should always use “*” for the sub fields property (attempts to instantiate non-recycling cursors with less than all fields will still result in all row object fields being hydrated).
6. After changing a row object, mark the object as changed and trigger propagation of the OnChanged message, as well as propagation of messages to related objects by calling the IRow::Store method on the object. Delete objects by calling the IRow::Delete method on the object triggering the OnDelete message. Stored and deleted objects within an edit operation are automatically and periodically flushed to the underlying database as needed to ensure read/query consistency and update efficiency. Use the set versions of these methods (for example, IRowEdit::DeleteSet) if updates or deletes are being made to a set of objects in order to increase performance.
7. Update and insert cursors are bulk data loading and data update API’s designed for performing direct updates and inserts, outside of an edit session, on simple data, during the data loading phase of a project. Avoid using these API’s in editing applications. Using these API’s within an edit session or on complex objects (objects with non-simple row or feature behavior or on objects participating in composite relationships or relationships with notification) negates any performance advantages they may have. For more information related to the above rules, see the documentation in this chapter on rows, objects, features tables, object classes, and feature classes.

Product Availability

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

Method Summary

void	abortEditOperation() Aborts an edit operation.
void	disableUndoRedo() Disables Undo and Redo of edit operations.
void	enableUndoRedo() Enables Undo and Redo of edit operations.
void	hasEdits(boolean[] pHasEdits) True if there are any completed edit operations that need to be saved .
void	hasRedos(boolean[] pHasRedos) True if there are any completed undos that can be redone.
void	hasUndos(boolean[] pHasUndos) True if there are any completed edit operations that can be undone.
boolean	isBeingEdited() True if the workspace is being edited.
void	redoEditOperation() Causes a Redo to be performed on the last undo.
void	startEditing(boolean withUndoRedo) Starts editing the workspace.
void	startEditOperation() Begins an edit operation.
void	stopEditing(boolean saveEdits) Stops editing the workspace.
void	stopEditOperation() Ends an edit operation.
void	undoEditOperation() Causes an Undo to be performed on the last edit operation.

Method Detail

startEditing

void startEditing(boolean withUndoRedo)
                  throws IOException,
                         AutomationException

Starts editing the workspace.

Remarks

An edit session may be started using the StartEditing method. The withUndoRedo parameter can be used to suppress undo/redo logging if the workspace supports such suppression. Note that the supression of undo/redo logging is not supported for remote database workspaces. StartEditing cannot be called when a edit session is already active. StopEditing must be called first before a new edit session can be started.

Note: With non-versioned editing always be sure to check the current edit state via IsBeingEdited before called StartEditing or StopEditing. If the workspace is being edited outside your context, there is no need to call StartEditing.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

withUndoRedo - The withUndoRedo (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

stopEditing

void stopEditing(boolean saveEdits)
                 throws IOException,
                        AutomationException

Stops editing the workspace.

Remarks

The StopEditing method is used to end an edit session. The saveEdits parameter controls if edits are saved or discarded. An ArcSDE geodatabase can support multiple concurrent edit sessions on the same version of the database. In such a scenario, StopEditing will return an error code of FDO_E_VERSION_REDEFINED if it detects that the database state associated with the version being edited is no longer the same as it was at the beginning of the edit session (indicating that the version was modified by some other edit session). In this case the application is responsible for calling the IVersionEdit::Reconcile method to reconcile the edit session against the current state of the version being edited. StopEditing may be called again after reconciliation.

Note: With non-versioned editing always be sure to check the current edit state via IsBeingEdited before called StartEditing or StopEditing. If the workspace is being edited outside your context, there will be issues if you call StopEditing. This will cause any other editors of the workspace to become decoupled with the potential loss of their edits.

This method explicitly commit of any active transactions in the database.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

saveEdits - The saveEdits (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isBeingEdited

boolean isBeingEdited()
                      throws IOException,
                             AutomationException

True if the workspace is being edited.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:

The pIsBeingEdited

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

startEditOperation

void startEditOperation()
                        throws IOException,
                               AutomationException

Begins an edit operation.

Remarks

All related changes to objects in the database within an edit session should be grouped into edit operations. An edit operation is begun using the StartEditOperation method. An edit operation may be thought of as a short transaction nested within the long transaction corresponding to the edit session.

All edits to features that participate in a Topology or Geometric Network must be bracketed within an edit operation.

When using StartEditOperation, proper handling of errors, including the use of AbortEditOperation, is neccessary.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

stopEditOperation

void stopEditOperation()
                       throws IOException,
                              AutomationException

Ends an edit operation.

Remarks

Applications are responsible for calling StopEditOperation to mark the end of a successfully completed edit operation. Completed edit operations can be thought of as being pushed onto an undo stack.

All edits to features that participate in a Topology or Geometric Network must be bracketed within an edit operation.

When using StopEditOperation, proper handling of errors, including the use of AbortEditOperation, is necessary.

This method explicitly commit of any active transactions in the database.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

abortEditOperation

void abortEditOperation()
                        throws IOException,
                               AutomationException

Aborts an edit operation.

Remarks

Applications are responsible for calling the AbortEditOperation method to abort an edit operation if errors are detected within the methods executed for an edit operation.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

hasUndos

void hasUndos(boolean[] pHasUndos)
              throws IOException,
                     AutomationException

True if there are any completed edit operations that can be undone.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

pHasUndos - The pHasUndos (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

undoEditOperation

void undoEditOperation()
                       throws IOException,
                              AutomationException

Causes an Undo to be performed on the last edit operation.

Remarks

The UndoEditOperation can be used to roll the state of the edit session back to what it was prior to the execution of the edit operation at the top of the undo stack. Undoing an edit operation pops the edit operation from the Undo stack and adds it to a Redo stack.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

hasRedos

void hasRedos(boolean[] pHasRedos)
              throws IOException,
                     AutomationException

True if there are any completed undos that can be redone.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

pHasRedos - The pHasRedos (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

redoEditOperation

void redoEditOperation()
                       throws IOException,
                              AutomationException

Causes a Redo to be performed on the last undo.

Remarks

The RedoEditOperation method rolls the state of the edit session forward to what it was after the execution of the edit operation at the top of the redo stack, pops the redone edit operation from the redo stack and pushes it back onto the undo stack. Performing a new edit operation clears the redo stack.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

enableUndoRedo

void enableUndoRedo()
                    throws IOException,
                           AutomationException

Enables Undo and Redo of edit operations.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

disableUndoRedo

void disableUndoRedo()
                     throws IOException,
                            AutomationException

Disables Undo and Redo of edit operations.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

hasEdits

void hasEdits(boolean[] pHasEdits)
              throws IOException,
                     AutomationException

True if there are any completed edit operations that need to be saved .

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:

pHasEdits - The pHasEdits (in/out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.