EDN: ESRI Developer Network
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster
The distributed geodatabase components allow you to transfer data between and distribute data across one or more geodatabases. A variety of data distribution strategies are supported including:
Distributed geodatabase components allow these and other operations to be performed using either geodatabase connections made over the LAN or using geodatabase connections served over the WAN using ArcGIS Server.
The library provides both coarse grained, stateless components as well as more fine grained components. The library includes the following object models:
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 the distributed geodatabase toolset overview.
The GeoDataServer Object Model is a high level, coarse grained, stateless object model that can be used for browsing, querying, data extraction, check out and check in and replication. It is a new object model introduced at ArcGIS 9.2. 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.
The Data Extraction and Check out/Check in Object Model is a lower level more fine grained object model that can also be used for data extraction and check out and check in. Applications should make use of the higher level GeoDataServer Object Model first and use these lower level objects only if additional fine grained functionality is required.
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, check out databases and replicas. It also contains very useful utility objects such as the VersionDataChanges that are generally useful in the context of versioning and editing.
The XML Export and Import Object Model can be used to export and import entire workspaces and feature classes from and to XML.
The Schema Change Export and Import Object Model can be used to export, compare and synchronize the schema of replicated geodatabases.
The GeoDataServer Object Model is a high level, coarse grained, stateless object model that can be used for browsing, querying, data extraction, check out and check in and replication.
Geodatabase Replication is the process of distributing data across two or more geodatabases such that they can periodically synchronize changes. Replication includes check out/check in replication, two way replication and one way replication. To create applications using this functionality, a developer should understand geodatabase replication concepts. Developers can also use the geodatabase replication geoprocessing functions within scripting environments as an alternative to developing ArcObjects applications.
The GeoDataServer class represents either a local 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 GeoDataServer from an ArcGIS Server connection.
The ReplicatonAgent class 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. A ReplicationAgent works with a pair of GeoDataServers. It can be used to create and synchronize replicas within the two GeoDataServers.
Figures 1 and 2 show examples of performing replication operations between two databases that are connected using computer networks (LAN or WAN) using the ReplicationAgent component. In Fig 1 the ReplicationAgent is working with local GeoDataServer objects each of which is initialized using a local client-server geodatabase connection over the LAN. In Fig 2, the ReplicationAgent is working with remote GeoDataServer objects served by ArcGIS Server over the WAN. For more information on ArcGIS Servers, see the ArcGIS Server documentation (ADD LINK HERE). Applications can use the CreateReplica and SynchronizeReplicas methods to create and synchronize replicas within the GeoDataServers.
For two way and one way replication, both geodatabases must be ArcSDE geodatabases. For check out/check in replication, the geodatabase hosting the parent replica must be an ArcSDE geodatabase. The geodatabase hosting the child replica may be either an ArcSDE or a personal geodatabase.
The GeoDataServer class exposes methods for working with a single geodatabase and for working with the replicas contained within that geodatabase. For example, the ExportDataChanges method exports the data changes for a replica to an XML file that can then be transported (by email, CD or any 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.
Figure 3 and 4 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 CD’s or DVD’s using non computer mail networks (e.g. using USPS, Fed EX etc).
The GeoDataServer component also exposes the ability to query and extract data in a geodatabase. Data extraction involves copying out a portion of some data in a geodatabase. The query functionality includes the ability to return rows from a table based on a queryfilter.
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 GeoData Server 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 GPReplica, GPReplicaDescription, GPReplicaDataset, GPReplicaOptions, GPVersionInfo, ResultPortionInfo and DataElement value objects.
A GeoDataServer can work with personal, file or ArcSDE geodatabases. Only ArcSDE based GeoDataServers will be capable of creating replicas. A GeoDataServer based on a personal or file geodatabase can still perform other operations such as querying, data extraction and export of data changes (if a child check-out replica).
The Data Extraction and Check out/Check in Object Model is a lower level and more fine grained object model. Applications should make use of the higher level GeoDataServer Object Model first and use these lower level objects only if additional fine grained functionality is required.
Both these low level components and the high level GeoDataServer components perform data extraction and check out and check in. However, these lower level components also support the following functionality:
This is a low level object model that contains some very useful utility objects for determining the changes made to a version or within an edit session.
The VersionDataChanges object can be 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 ReplicaDataChanges are low level components that are made use of by replication and check-out 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 EditDataChanges objects from the geodatabase libraray can be used to determine the changes to a workspace within an edit session or within an 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. See the geodatabase object model for more information.
Differences are exported to and imported from delta files. Delta files can be stored in either of three storage types: delta XML files, delta databases (MDB) and 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 also support 2 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 at edit time. This requires a full geodatabase editor like the one provided in 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 class is used to generate delta files for version differences and replicas. Another way to generate a delta file is by writing an application that generates an XML updategram document. The XML updategram format is published and available for you to develop with. This format enables you to generate delta files for any data source. For example, you could create an application to write edits made to a shapefile to an XML delta file which can then be imported into an ArcSDE geodatabase. Delta files generated this way should be created as simple model type documents since the edits were not performed with a geodatabase-aware editor.
The diagram below summarizes this discussion on the ways delta files can be used to transfer changes:
The DataChangesImporter class can be used to import changes from delta files generated from any of the methods described above. To import changes you must first instantiate a DeltaDataChanges object and then pass it into the DataChangesImporter. The following table lists several factors that must be considered when importing changes:
| Factor | Description |
|---|---|
| Delta file model type | Both full and simple model types are supported for any valid delta file. Some types of behavior can't be applied with simple model type delta files. 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 which 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 may 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 GlobalID’s, you may 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 delta files 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 gets 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 gets 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. |
The XML import and Export components allow you to export and import data from a geodatabase using XML workspace or XML recordset documents.
Below is a summary of the functionality provided by each class:
The GDBImporter is used to import into a geodatabase from an XML workspace or XML recordset document.
The 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.
The 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.
The Schema Change Export and Import Object model is a lower level and more fine grained object model. Applications should make use of the higher level GeoDataServer Object Model and use these lower level objects only if additional fine grained functionality is required.
Like 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.