docs: public void add(ManagedObject managedObject,
                      boolean requiresCurrentCheckpoint)
                      throws ObjectManagerException
      {
          final String methodName = "add";
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.entry(this,
                          cclass,
                          methodName,
                          new Object[] { managedObject, new Boolean(requiresCurrentCheckpoint) });
  
          super.add(managedObject, requiresCurrentCheckpoint);
  
          // Replacements are detected at flush time,
          // we free the space occupied by any previous version after we have written
          // the new one.
  
          // TODO Better to change the maps to use a single identifier returned by the
          // ManagedObject.
          //      This would save newing up Long().
  
          // Include this to the set of ManagedObjects to write, if its not already included.
          if (requiresCurrentCheckpoint
              && storeStrategy != STRATEGY_SAVE_ONLY_ON_SHUTDOWN) {
              // The checkpoint logic in ObjectManagerState never calls flush until all of the
              // requiresCurrentCheckpoint transactions have been checkpointed. So no need to synchronize 
              // on checkpointManagedObjectsToWrite once we have made sure it exits.
              if (checkpointManagedObjectsToWrite == null)
                  captureCheckpointManagedObjects();
  
              checkpointManagedObjectsToWrite.put(new Long(managedObject.owningToken.storedObjectIdentifier),
                                                  managedObject);
  
          } else {
              for (;;) {
                  // Repeat requests to write until we can see the same Map after we have done the insertion, 
                  // this means that we will have been included in at least one flush.
                  java.util.Map myManagedObjectsToWrite = managedObjectsToWrite;
                  myManagedObjectsToWrite.put(new Long(managedObject.owningToken.storedObjectIdentifier),
                                              managedObject);
                  // Make sure the flush() did not steal managedObjectsToWrite while we were adding to it.
                  if (myManagedObjectsToWrite == managedObjectsToWrite)
                      break;
              } // for(;;).
          }
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.exit(this,
                         cclass,
                         methodName);
      }