This document is archived and information here might be outdated.  Recommended version.


GeoDatabaseDistributed
ArcObjects namespaces > GeoDatabaseDistributed

GeoDatabaseDistributed


Supported with:
  • Engine
  • ArcGIS for Desktop Basic
  • ArcGIS for Desktop Standard
  • ArcGIS for Desktop Advanced
  • Server
Library dependencies: Version, System, SystemUI, Geometry, GraphicsCore, Display, Server, Output, Geodatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF

Additional library information: Contents, Object Model Diagram

The GeodatabaseDistributed library components allow you to transfer data between, and distribute data across, one or more geodatabases. A variety of data distribution strategies are supported including the following:
  • Making simple copies or extracts of data.
  • Creating checkouts of the data for subsequent editing and check-in.
  • Creating replicas that support periodic synchronizations.
Distributed geodatabase components allow these and other operations to be performed using either geodatabase connections made over a local area network (LAN) or using geodatabase connections served over a wide area network (WAN) using ArcGIS for Server.
In addition to the components in this library, a number of geoprocessing tools are available for performing distributed geodatabase operations. These tools are implemented using the coarse grained GeodataServer object model and are part of the distributed geodatabase toolset. For more information on using these tools in applications, see An overview of the Distributed Geodatabase toolset.

See the following sections for more information about this namespace:

GeodataServer object model

The GeodataServer object model is a high level, coarse grained, stateless object model that can be used for browsing, querying, data extraction, checkout and check-in, and replication. It is the highest level object model; application developers are advised to investigate meeting their requirements using this object model before investigating the lower level object models.
Geodatabase replication is the process of distributing data across two or more geodatabases so that they can periodically synchronize changes. Replication includes checkout/check-in replication, two-way replication, and one-way replication. To create applications using this functionality, you need to understand geodatabase replication concepts. You can also use the geodatabase replication geoprocessing functions within scripting environments as an alternative to developing ArcObjects applications.
The GeodataServer coclass represents either a local geodatabase or a remote geodatabase. Applications can create a GeodataServer and initialize it using a LAN connection to a geodatabase. Applications can also obtain a proxy to a remote geodata server from an ArcGIS for Server connection.
The ReplicationAgent coclass is a software component that can be used to implement replication commands and agents (services). The fundamental unit of replication is a replica pair consisting of a parent replica and a child replica. ReplicationAgent works with a pair of GeodataServers. It can be used to create and synchronize replicas within the two GeodataServers.
Connected replication using the ReplicationAgent component
The following diagram shows connected replication over a LAN using the ReplicationAgent and GeodataServer components:
The following diagram shows connected replication over a WAN using the ReplicationAgent and GeodataServer components:
Both of these diagrams show examples of performing replication operations between two databases that are connected using computer networks (LAN or WAN) using the ReplicationAgent component. In the first diagram, the ReplicationAgent is working with local GeodataServer objects, each of which is initialized using a local client-server geodatabase connection over a LAN. In the second diagram, the ReplicationAgent is working with remote GeodataServer objects served by ArcGIS for Server over a WAN. Applications can use the CreateReplica and SynchronizeReplica methods to create and synchronize replicas in GeodataServer.
For two-way replication, both geodatabases must be ArcSDE geodatabases. For checkout/check-in replication and one way replication, the geodatabase hosting the parent replica must be an ArcSDE geodatabase. The geodatabase hosting the child replica can be either an ArcSDE geodatabase or a personal geodatabase.
The GeodataServer coclass exposes methods for working with a single geodatabase and for working with the replicas contained in that geodatabase. For example, the ExportDataChanges method exports the data changes for a replica to an Extensible Markup Language (XML) file that can then be transported (by e-mail, CD, or other mechanism) to another site. The CreateReplica method outputs an XML file that can be imported into another GeodataServer object to complete the replica creation process.
Disconnected replication using the GeodataServer component
The following diagram shows disconnected replication using GeodataServer components on a LAN:
The following diagram shows disconnected replication using GeodataServer components on a WAN:
The previous two diagrams show examples of using the GeodataServer component to perform replication operations between two databases that are not connected by computer networks. In these disconnected examples, communication is done by exchanging delta files or workspace XML files. Methods on the GeodataServer are used to export or import these files. The files can be sent between the geodatabases using a distribution process involving transmitting CDs or DVDs using non-computer mail networks (for example, USPS, Federal Express, and so on).
Querying and extracting data with GeodataServer
The GeodataServer component gives you the ability to query and extract data in a geodatabase. Data extraction involves copying a portion of some data in a geodatabase. The query functionality includes the ability to return rows from a table based on a query filter.
Methods are also available to return information about the geodatabase referenced by the geodataserver. For example, you can get a list of versions or a list of domains that exist in the geodatabase.
Some of the components in the GeodataServer object model are value objects used as inputs and outputs to the methods on the ReplicationAgent and GeodataServer components. These include GDSData, GDSQueryResultPortion, and GDSExportOptions. Additional value objects from the Geodatabase object library are also used. They include the following value objects:
GeodataServer can work with personal, file, or ArcSDE geodatabases. Only ArcSDE-based geodataservers are capable of creating replicas. A geodataserver that is based on a personal or file geodatabase can still perform other operations such as query, data extraction, and export of data changes (if it's a child checkout replica).
The Data Extraction and Checkout/Check-in object model is a lower level, more fine grained object model that can also be used for data extraction and checkout and check-in. It was first released as the data extraction and disconnected editing application programming interface (API). New applications should use the higher level GeodataServer object model and use the lower level objects only if additional fine grained functionality is required.

For further information see:

How to create a replica in a connected environment
How to synchronize a replica in a connected environment
How to create a replica in a disconnected environment
How to synchronize a data change message in a disconnected environment
How to synchronize an acknowledgement message in a disconnected environment

Data Changes object model

The Data Changes object model is a lower level, fine grained object model that can be used to obtain the data changes made to or contained in a variety of distributed geodatabase objects. These include delta files, checkout databases, and replicas. It also contains utility objects, such as VersionDataChanges, that are useful when versioning and editing.
The VersionDataChanges object is used to determine the changes made in a version since the time it shared a common state with an ancestor version. Applications can determine the set of tables and feature classes that were changed, and for each changed feature class, applications can extract the inserts, updates, and deletes made to the class. CheckOutDataChanges and ReplicationDataChanges are low level components that are used during replication checkout and check-in.
The high level components expose some of this functionality in that they provide methods to export and import delta files for replicas. However, these low level components also provide the following:
  • The ability to export and import differences between versions in ArcSDE geodatabases.
  • The ability to import changes from custom delta files that can be generated from non-geodatabase formats.
  • Methods to return information from the delta file including information about the edits described in the file.
  • Methods to return information about the edits that have been applied to a replica since it was last synchronized.
The EditDataChangesType constants from the Geodatabase library can be used to determine the changes to a workspace in an edit session or edit operation. Applications can determine the set of tables and feature classes that were changed, and for each changed feature class, applications can extract the inserts, updates, and deletes made to the class.

Delta files, updategrams, and data exchange

Differences are exported to, and imported from, delta files. Delta files can be stored in any of the following three storage types:
  • Delta XML files
  • Delta databases (MDB)
  • Delta file geodatabases
A delta XML file is also referred to as an XML updategram document and has a published format. The other formats are proprietary.
Delta XML files support two model types: full model type and simple model type. Delta databases and delta file geodatabases support only the full model type.
A full model type delta file indicates that all reactive geodatabase behavior was executed upon editing. This requires a full geodatabase editor such as the one provided with ArcMap. With the full model, no additional geodatabase behavior is applied when the edits are imported because it has already been applied with the geodatabase editor. These types of delta files can be used in systems where all data sources involved are geodatabases.
A simple model type delta file assumes that the edits were not made by a reactive geodatabase editor. When importing from a simple model type, the reactive behavior is applied during the import. These types of delta files are useful in systems where some of the data sources involved are not geodatabases. For example, you may want to apply edits made in a shapefile or a non-ArcGIS data format to your geodatabase.
The DataChangesExporter coclass is used to generate delta files for version differences and replicas. Applications can also be written to generate custom updategrams from any data source. The updategrams generated by these applications can be written to an XML delta file or based on changes defined by the TablesDataChanges coclass. For example, you could create an application to write edits made to a shapefile to an XML delta file that can then be imported to an ArcSDE geodatabase. Updategrams generated this way should be created as simple model type documents since the edits were not performed with a geodatabase-aware editor.
The following diagram summarizes how delta files can be used to transfer changes.
The DataChangesImporter coclass can be used to import changes from updategrams generated from any of the methods previously described. To import changes, you must first instantiate a DeltaDataChanges object from a delta file or use the TablesDataChanges object, then pass it to DataChangesImporter.
The following table lists several factors that must be considered when importing changes:
Factor
Description
Updategram model type Both full and simple model types are supported for any valid updategram. Some types of behavior can't be applied with a simple model type. For example, if a simple model delta file has an update that moves or rotates a feature with feature linked annotation, the annotation is not automatically adjusted on import.
GlobalID columns
Data can have a column of type GlobalID. GlobalID columns contain a unique GUID value for each row that is maintained by ArcGIS. This column is similar to the ObjectID column except that the GlobalID value uniquely identifies the row across geodatabases. If it exists, the GlobalID value is used to apply the edits; otherwise, the ObjectID value is used.
When importing, the ObjectID value for an insert row can be modified to make it unique within the table. The GlobalID value is never modified, since it is unique across geodatabases. If you plan on importing changes over several cycles, it may be necessary to add GlobalID columns to your data. Without GlobalIDs, you can insert the same row several times into the database. See the IClassSchemaEdit3 interface for methods to add and drop these columns.
Import version and geodatabase When importing a delta file that was generated from a replica, edits are always imported into the replica version. For updategrams generated from version changes or custom applications, the edits can be imported into any version in any geodatabase. The import will succeed as long as the datasets for the data described in the delta file are versioned and editable for your ArcSDE user.
When importing data with a GlobalID column, behavior is applied to ensure that a single GlobalID value refers to the same row throughout the geodatabase. For example, if you are importing an insert that has already been inserted into the geodatabase, it gets applied as an update.
The following table describes how inserts, updates, and deletes are applied based on conditions in the import version:
Scenario
Result A - with a GlobalID
Result B - without a GlobalID
INSERT: The delta file insert row already exists in the import version. The row is added as an update. The row is inserted into the import version as a new row with a new ObjectID value.
INSERT: The delta file insert row does not exist in the import version but exists in another version in the geodatabase. A. The insert is skipped if it exists in a non-ancestor version. You can use reconcile and post to move the row into the import version.
B. The insert is applied as an update if it exists in an ancestor version.
The row is inserted into the import version as a new row with a new ObjectID value.
INSERT: The delta file insert row is not found in the geodatabase. The row is inserted into the import version as a new row with a new ObjectID value. The row is inserted into the import version as a new row with a new ObjectID value.
UPDATE: The delta file update row already exists in the import version. The update is applied. The update is applied.
UPDATE: The delta file update row does not exist in the import version but exists in another version in the geodatabase. A. The update is skipped if it exists in a non-ancestor version. You can use reconcile and post to move the row into the import version.
B. The update row is applied as an update if it exists in an ancestor version.
The update is skipped.
UPDATE: The delta file update row is not found in the geodatabase. The update is skipped. The update is skipped.
DELETE: The delta file delete row is found in the import version. The row is deleted. The row is deleted.
DELETE: The delta file delete row is not found in the import version. The delete is skipped. The delete is skipped.

XML Export and Import object model

The XML Export and Import object model can be used to export and import entire workspaces and feature classes from and to XML. The XML Export and Import components allow you to export and import data from a geodatabase using XML workspace or XML recordset documents.
A summary of the functionality provided by each coclass is as follows:
  • GdbImporter is used to import into a geodatabase from an XML workspace or XML recordset document.
  • GdbExporter is used to export all data in a geodatabase to a workspace XML document or a subset of data to a recordset XML document.
  • GdbSchemaCreator is used to create geodatabase schema and domains from a workspace or dataset data element as well as from the contents of an XML document.
Samples
See the individual coclass topics and their methods for code examples.

Schema Change Export and Import object model

The Schema Change Export and Import object model can be used to export, compare, and synchronize the schema of replicated geodatabases. The Schema Change Export and Import object model is a lower level and more fine grained object model. Applications should use the higher level GeodataServer object model and use these lower level objects only if additional fine grained functionality is required.
As with the GeodataServer object model, these components allow you to export replica schemas, compare replica schemas, and import replica schema changes using XML files. These lower level components also provide the following functionality:
  • The SchemaChanges and SchemaChangeInfo coclasses have methods to return information about replica schemas and replica schema comparisons.
  • The SchemaChanges and SchemaChangeInfo coclasses also allow you to choose whether or not to apply specific schema changes before importing the changes.
  • If both replica geodatabases are on the same network, ReplicaSchemaExporter allows a schema comparison by directly comparing the geodatabases. The replica schemas do not need to be exported to an XML file.