com.esri.arcgis.geodatabase
Interface IMultiuserWorkspaceEdit

All Superinterfaces:

Serializable

All Known Implementing Classes:

IMultiuserWorkspaceEditProxy

public interface IMultiuserWorkspaceEdit
extends Serializable

Provides access to members that control Multiuser Workspace Editing.

Remarks

The IMultiuserWorkspaceEdit interface allows the application to start and stop edit sessions during which the objects in a geodatabase can be updated. This differs from the IWorkspaceEdit interface in that the IMultiuserWorkspaceEdit interface is only supported by workspaces that support both edit session modes, namely enterprise geodatabases.

It should be noted that the IWorkspaceEdit::StopEditing method is still used to stop an edit session whether it is started using the IWorkspaceEdit::StartEditing or IMultiuserWorkspaceEdit::StartMultiuserEditing methods.

If the IMultiuserWorkspaceEdit interface is used the edit session can be started in either versioned or non versioned edit session modes. If the edit session mode is set to versioned the only changes to data that an application sees within an edit session are changes that are made by that application. Changes made by other concurrently executing applications (if allowed) are not seen until the edit session is saved or discarded. On the other hand, editing within an edit session in non versioned mode is the equivalent of performing standard database transactions. You still perform the edits within a standard edit session however when you’ve finished, the changes are committed as a single transaction by saving. If you don’t want to commit the changes, you abort the edit session without saving. Each transaction can include as few or as many operations as required, provided they fall within a single edit session.

Non versioned editing edits the data source directly – it doesn’t store the changes in other tables like versioned editing does. This avoids the overhead of managing these extra tables, and allows you to easily adapt non-ESRI applications so that they can read and edit the data. However, the drawback is that since you edit the data source directly, you cannot undo or redo an individual edit if you make a mistake. The only way to undo edits is to undo all edits by quitting the edit session without saving. You can perform non versioned edits on simple data only – points, lines, polygons, annotation, and relationships. You cannot perform non versioned edits on feature classes in a topology or geometric network.

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 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 StartMultiuserEditing 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 StartMultiuserEditing.

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 StartMultiuserEditing). 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. 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 geodatabases 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 only be used for drawing and read-only access to a perticular object's 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

int	getMultiuserEditSessionMode() getMultiuserEditSessionMode
void	startMultiuserEditing(int esMode) startMultiuserEditing
boolean	supportsMultiuserEditSessionMode(int esMode) supportsMultiuserEditSessionMode

Method Detail

getMultiuserEditSessionMode

int getMultiuserEditSessionMode()
                                throws IOException,
                                       AutomationException

getMultiuserEditSessionMode

Remarks

Returns an esriMultiuserEditSessionMode enumeration corresponding to the current edit session mode.

Product Availability

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

Returns:

A com.esri.arcgis.geodatabase.esriMultiuserEditSessionMode constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

supportsMultiuserEditSessionMode

boolean supportsMultiuserEditSessionMode(int esMode)
                                         throws IOException,
                                                AutomationException

supportsMultiuserEditSessionMode

Remarks

The SupportsMultiuserEditSessionMode method returns a boolean corresponding to whether the particular workspace supports the edit session mode that is specified as an argument. This property will return true if the specified edit session mode is supported. It is important to note that non versioned edit session mode is not supported by any data that is registered as versioned.

Product Availability

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

Parameters:

esMode - A com.esri.arcgis.geodatabase.esriMultiuserEditSessionMode constant (in)

Returns:

The isSupported

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

startMultiuserEditing

void startMultiuserEditing(int esMode)
                           throws IOException,
                                  AutomationException

startMultiuserEditing

Remarks

The StartMultiuserEditing method can be used to start an edit session in either versioned or non versioned edit session mode. This method has one argument esMode which corresponds to the esriMultiuserEditSessionMode enumeration.

Calling the StartMultiuserEditing(esriMESMVersioned) method is synonymous to calling the IWorkspaceEdit::StartEditing(True) method. Both calls will result in the begining of an edit session in the versioned edit session mode.

It should be noted that the IWorkspaceEdit::StopEditing method is still used to stop an edit session whether it is started using the IWorkspaceEdit::StartEditing or IMultiuserWorkspaceEdit::StartMultiuserEditing methods.

Product Availability

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

Parameters:

esMode - A com.esri.arcgis.geodatabase.esriMultiuserEditSessionMode constant (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.