Recursion Details

Almost every Gravity DAO method takes an ObjectFieldsDepthLevel enum as a parameter. This controls how associated object (i.e. single or multiple object) fields and child object lists are handled. The options are:

• OnlyParentObject (no recursion)
• FirstLevelOnly (first level is recursed, but recursive operations run under OnlyParentObject)
• FullyRecursive.

These mean similar, but not identical, things for different API calls:

• Get/Query
  • When recursion is off
    • Associated objects are populated with stubs just containing the ArtifactID
    • Child object lists are not populated at all.
    • Other field are set.
  • When recursion is on, Get/Query is called on each associated/child object to fill in the stub.
• Delete
  • Associated objects are unlinked before deletion.
  • If there are any child objects in the database (not your model) past the "recursion threshold", an exception will be thrown and no objects will be deleted.
    • Otherwise, the root object and all descending objects are deleted.
• Insert
  • Existing associated objects are linked to the new object, but the object itself is not updated and recursion occurs on that object
  • If recursion is off, child and new associated objects are not inserted; their ArtifactID remains 0
  • If recursion is on, child and new objects are created, and Insert is called on those objects if FullyRecursive.
• Update
  • If recursion is off
    • Existing associated objects are linked/unlinked by Artifact ID
    • New associated objects and all child objects are ignored
  • If recursion is on
    • Existing associated objects are linked/unlinked, and Update is called on the linked ones in turn
    • Insert is called on new associated and child objects
    • Update is called on Existing child objects
    • Delete is called on child objects present in the database, but not on the model

It follows that your write operations should never have a greater degree of recursion than your read operations. For example, if you read at OnlyParentObject, then write that result with FirstLevelOnly, all of your child objects will be deleted.