docs: private void updateDirectory()
                      throws ObjectManagerException
      {
          final String methodName = "updateDirectory";
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.entry(this,
                          cclass,
                          methodName);
  
  // TODO See below for how to deal with out of disk space conditions.    
  //    // Keep the current disk location of the directory.
  //    long currentDirectoryRootAddress = ((Directory.Node)directory.root).byteAddress;
  //    long currentDirectoryRootLength = ((Directory.Node)directory.root).length;
  //    long currentStoreFileSizeUsed = storeFileSizeUsed;
  //    
  //    long newFreeSpaceLength;
  //    long newFreeSpaceByteAddress; 
  
  //  try {    
          // Capture the ManagedObjects to write and delete. The checkpoint manager has does not 
          // call flush until all transactions have completd their checkpoint activity.
          // If we have not seen any chekpoint updates truncate the write and delete sets now. 
          if (checkpointManagedObjectsToWrite == null)
              captureCheckpointManagedObjects();
  
          // Defect 573905
          // Free space clear moved to end of flush.
  
          // The reserved space we will release once the flush has written all it needs to the disk.
          checkpointReleaseSize = 0;
  
          if (gatherStatistics) // Start the clock.
              lastFlushMilliseconds = System.currentTimeMillis();
  
          // 1) Update the directory.
          // ------------------------
          // New write updates are not updating checkpointManagedObjectsToWrite, we have a safe set.
          for (java.util.Iterator managedObjectIterator = checkpointManagedObjectsToWrite.values().iterator(); managedObjectIterator.hasNext();) {
              ManagedObject managedObject = (ManagedObject) managedObjectIterator.next();
              cache(managedObject);
              write(managedObject);
          } // For ... checkpointManagedObjectsToWrite.
          checkpointManagedObjectsToWrite = null;
  
          if (gatherStatistics) {
              long now = System.currentTimeMillis();
              writingMilliseconds += now - lastFlushMilliseconds;
              lastFlushMilliseconds = now;
          } // if (gatherStatistics).
  
          // Remove Objects from the directory and make a note of any free space that we can release
          // once we have allocated all of the new space we will need.    
          for (java.util.Iterator tokenIterator = checkpointTokensToDelete.values().iterator(); tokenIterator.hasNext();) {
              Token token = (Token) tokenIterator.next();
              // Delete the object by removing it from the directory, we dont touch
              // the data on the disk.
              Directory.StoreArea storeArea = (Directory.StoreArea) directory.removeEntry(new Long(token.storedObjectIdentifier));
              // Did we ever write this?
              if (storeArea != null)
                  newFreeSpace.add(storeArea);
          } // For ... checkpointTokensToDelete.
          checkpointTokensToDelete = null;
  
          if (gatherStatistics) {
              long now = System.currentTimeMillis();
              removingEntriesMilliseconds += now - lastFlushMilliseconds;
              lastFlushMilliseconds = now;
          } // if (gatherStatistics).
  
          // 2) Allocate new space for the directory and the free space map.
          // ---------------------------------------------------------------
          if (Tracing.isAnyTracingEnabled() && trace.isDebugEnabled())
              trace.debug(this,
                          cclass,
                          methodName,
                          "Reserve space for the direcory and new free space map");
  
          // All changes have been made to the directory, now reserve space in the file for any updates 
          // and release any space which will become free.
          directory.reserveSpace();
  
          if (gatherStatistics) {
              long now = System.currentTimeMillis();
              allocatingEntrySpaceMilliseconds += now - lastFlushMilliseconds;
              lastFlushMilliseconds = now;
          } // if (gatherStatistics).
  
          if (freeSpaceStoreArea != null && freeSpaceStoreArea.length != 0)
              newFreeSpace.add(freeSpaceStoreArea);
          // Make a worst case assumption that no new free space will merge with the 
          // existing free space.
          long newFreeSpaceLength = (freeSpaceByLength.size() + newFreeSpace.size()) * freeSpaceEntryLength;
          FreeSpace newFreeSpaceArea = allocateSpace(newFreeSpaceLength);
  
          //TODO The following code segment will restore the ObjectStore to the state ir was in before we ran out
          //TODO of disk space, however the serialized bytes will now have been released from the ManagedObjects. 
  //    } catch (ObjectStoreFullException objectStoreFullException) {
  //      // No FFDC code needed.
  //      if (Tracing.isAnyTracingEnabled() && trace.isEventEnabled())
  //        trace.event(this,
  //                    cclass,
  //                    methodName,
  //                    objectStoreFullException);
  //      
  //      // Not enough space was available to make the update. 
  //      // Perhaps insufficient reservation() was done?
  //      // Put things back the way they were.
  //      managedObjectsToWrite.putAll(checkpointManagedObjectsToWrite);
  //      tokensToDelete.putAll(checkpointTokensToDelete);
  //      // Revert to the disk copy of the directory, if there is none
  //      // the length will be zero so we will create a new empty directory.
  //      directory = readDirectory(directory.getMinimumNodeSize(),
  //                                currentDirectoryRootAddress,
  //                                currentDirectoryRootLength);
  //      
  //      storeFileSizeUsed = currentStoreFileSizeUsed;
  //      
  //      if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
  //        trace.exit(this,
  //                   cclass,
  //                   methodName,
  //                   new Object[]{objectStoreFullException});
  //      throw objectStoreFullException;      
  //    } // try...
  
          // All space allocation is now done.   
          freeSpaceStoreArea = directory.makeStoreArea(freeSpaceIdentifier,
                                                       newFreeSpaceArea.address,
                                                       newFreeSpaceArea.length);
  
          // Adjust the space we need to safely remove entries from the directory.
          // The worstCaseDirectorySpace is an over estimate of the space needed so we might 
          // prematurely stop allocations.
          directoryReservedSize = directory.spaceRequired();
          // Give back all space that was previously reserved, but which has now been written.
          reservedSize.addAndGet(-checkpointReleaseSize);
  
          // See if the store is too now full to allow further ManagedObject allocation.
          // Also set the reservation thresholds.
          setAllocationAllowed();
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.exit(this,
                         cclass,
                         methodName);
      }