docs: private void readFreeSpaceMap(long freeSpaceCount)
                      throws ObjectManagerException
      {
          final String methodName = "readFreeSpaceMap";
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.entry(this,
                          cclass,
                          methodName,
                          new Object[] { new Long(freeSpaceCount) });
  
          freeSpaceByAddressHead = null;
          freeSpaceByLength = new java.util.TreeSet(new AbstractSingleFileObjectStore.LengthComparator());
          // Load the free space map.
          if (freeSpaceStoreArea != null) {
              try {
                  storeFile.seek(freeSpaceStoreArea.byteAddress);
                  FreeSpace freeSpaceByAddressTail = null;
                  for (int i = 0; i < freeSpaceCount; i++) {
                      AbstractSingleFileObjectStore.FreeSpace freeSpace =
                                      new AbstractSingleFileObjectStore.FreeSpace(storeFile.readLong(), storeFile.readLong());
  
                      // If we are switching to using a sorted free space map, then
                      // we may find the map we load from the store is unsorted.
                      // In this case we take a hit on sorting it during the first
                      // startup after it is enabled.
                      if (freeSpaceByAddressTail != null && freeSpace.address < freeSpaceByAddressTail.address) {
                          FreeSpace sortEntry = freeSpaceByAddressHead;
                          while (sortEntry != null) {
                              // Have we just gone past where this entry should be inserted?
                              if (sortEntry.address > freeSpace.address) {
                                  // Add it before the current entry.
                                  freeSpace.next = sortEntry;
                                  freeSpace.prev = sortEntry.prev;
                                  if (sortEntry.prev != null) {
                                      sortEntry.prev.next = freeSpace;
                                  }
                                  else {
                                      freeSpaceByAddressHead = freeSpace;
                                  }
                                  sortEntry.prev = freeSpace;
                                  break;
                              }
                              sortEntry = sortEntry.next;
                          }
                          // Check we found a place to insert it
                          if (sortEntry == null) {
                              // No FFDC Code Needed.
                              Exception exception = new RuntimeException();
                              ObjectManager.ffdc.processException(this, cclass, methodName, exception, "1:365:1.35");
                              if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                                  trace.exit(this,
                                             cclass,
                                             "readFreeSpaceMap");
                              throw new UnexpectedExceptionException(this, exception);
                          }
                          // The tail remains unchanged in this case, as we can't get to this
                          // block unless there is already a tail, and our entry is before it.
                      }
                      // Otherwise we simply add this entry to the tail
                      else {
                          // Are we the first entry?
                          if (freeSpaceByAddressTail == null) {
                              freeSpaceByAddressHead = freeSpace;
                          }
                          else {
                              freeSpace.prev = freeSpaceByAddressTail;
                              freeSpaceByAddressTail.next = freeSpace;
                          }
                          // The tail is now our new entry
                          freeSpaceByAddressTail = freeSpace;
                      }
  
                      // Add the entry to the length-sorted list 
                      freeSpaceByLength.add(freeSpace);
                  } // for directoryCount.
  
              } catch (java.io.IOException exception) {
                  // No FFDC Code Needed.
                  ObjectManager.ffdc.processException(this, cclass, methodName, exception, "1:395:1.35");
  
                  if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                      trace.exit(this,
                                 cclass,
                                 methodName);
  
                  // cannot continue
                  objectManagerState.requestShutdown();
                  throw new PermanentIOException(this,
                                                 exception);
              } // catch (java.io.IOException exception).
          } // if (freeSpaceStoreArea != null).
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.exit(this,
                         cclass,
                         methodName);
      }