From 4ae9f6a1076acbcf596c1b36ff418cafff3fa2f0 Mon Sep 17 00:00:00 2001 From: ctingue Date: Fri, 28 Oct 2016 11:56:39 -0700 Subject: [PATCH] Add documentation for ForeignKeyIndex and EppResourceIndex ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=137536233 --- docs/code-structure.md | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/code-structure.md b/docs/code-structure.md index 21f4a1853..1e01bb766 100644 --- a/docs/code-structure.md +++ b/docs/code-structure.md @@ -82,7 +82,7 @@ are multiple cursors per operation; for instance, the cursors related to RDE reporting, staging, and upload are per-TLD cursors. To accomplish this, each `Cursor` also has a scope, a `Key` to which the particular cursor applies (this can be e.g. a `Registry` or any other `ImmutableObject` in -datastore, depending on the operation). If the `Cursor` applies to the entire +Datastore, depending on the operation). If the `Cursor` applies to the entire registry environment, it is considered a global cursor and has a scope of `EntityGroupRoot.getCrossTldKey()`. @@ -187,6 +187,38 @@ There are a number of other useful utility methods for interacting with EPP resources in the `EppResourceUtils` class, many of which deal with inspecting the status of a resource at a given point in time. +## Foreign key indexes + +Foreign key indexes provide a means of loading active instances of `EppResource` +objects by their unique IDs: + +* `DomainResource`: fully-qualified domain name +* `ContactResource`: contact id +* `HostResource`: fully-qualified host name + +Since all `EppResource` entities are indexed on ROID (which is also unique, but +not as useful as the resource's name), a `ForeignKeyIndex` provides a way to +look up the resources using another key which is also unique during the lifetime +of the resource (though not for all time). + +A `ForeignKeyIndex` is updated as a resource is created or deleted. It is +important to note that throughout the lifecycle of an `EppResource`, the +underlying Datastore entity is never hard-deleted; its deletion time is set to +the time at which the EPP command to delete the resource was set, and it remains +in Datastore. Other resources with that same name can then be created. + +## EPP resource index + +An `EppResourceIndex` is an index that allows for quick enumeration of all +`EppResource` entities in Datastore. Datastore does not otherwise provide an +easy way to efficiently and strongly consistently enumerate all entities of a +given type. Each `EppResourceIndex` is assigned randomly to an +`EppResourceIndexBucket` upon creation, the number of which is configured to be +greater than the number of shards typically used for Mapreduces that enumerate +these entities. Mapreduces that process all `EppResource` entities (or +subclasses thereof) distribute each `EppResourceIndexBucket` to available +shards. + ## History entries A `HistoryEntry` is a record of a mutation of an EPP resource. There are various