claimChild method

RestorationBucket claimChild(
  1. String restorationId, {
  2. required Object? debugOwner,
})

Claims ownership of the child with the provided restorationId from this bucket.

If the application is getting restored to a previous state, the bucket will contain all the data that was previously stored in the bucket. Otherwise, an empty bucket is returned.

The claimer of the bucket is expected to use the data stored in the bucket to restore itself to its previous state described by the data in the bucket. If the bucket is empty, it should initialize itself to default values. Whenever the information that the claimer needs to restore its state changes, the data in the bucket should be updated to reflect that.

A child bucket with a given restorationId can only have one owner. If another owner claims a child bucket with the same restorationId an exception will be thrown at the end of the current frame unless the previous owner has either deleted its bucket by calling dispose or has moved it to a new parent via adoptChild.

When the returned bucket is no longer needed, it must be disposed to delete the information stored in it from the app's restoration data.

Implementation

RestorationBucket claimChild(String restorationId, {required Object? debugOwner}) {
  assert(_debugAssertNotDisposed());
  // There are three cases to consider:
  // 1. Claiming an ID that has already been claimed.
  // 2. Claiming an ID that doesn't yet exist in [_rawChildren].
  // 3. Claiming an ID that does exist in [_rawChildren] and hasn't been
  //    claimed yet.
  // If an ID has already been claimed (case 1) the current owner may give up
  // that ID later this frame and it can be re-used. In anticipation of the
  // previous owner's surrender of the id, we return an empty bucket for this
  // new claim and check in [_debugAssertIntegrity] that at the end of the
  // frame the old owner actually did surrendered the id.
  // Case 2 also requires the creation of a new empty bucket.
  // In Case 3 we create a new bucket wrapping the existing data in
  // [_rawChildren].

  // Case 1+2: Adopt and return an empty bucket.
  if (_claimedChildren.containsKey(restorationId) || !_rawChildren.containsKey(restorationId)) {
    final RestorationBucket child = RestorationBucket.empty(
      debugOwner: debugOwner,
      restorationId: restorationId,
    );
    adoptChild(child);
    return child;
  }

  // Case 3: Return bucket wrapping the existing data.
  assert(_rawChildren[restorationId] != null);
  final RestorationBucket child = RestorationBucket.child(
    restorationId: restorationId,
    parent: this,
    debugOwner: debugOwner,
  );
  _claimedChildren[restorationId] = child;
  return child;
}