docs: FreeSpace allocateSpace(long lengthRequired)
                      throws ObjectManagerException
      {
          final String methodName = "allocateSpace";
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.entry(this,
                          cclass,
                          methodName,
                          new Object[] { new Long(lengthRequired) });
  
          // Find some free space, first search the free space map for the smallest
          // entry that will accommodate the request.
          FreeSpace freeSpace;
  
          java.util.SortedSet tailSet = freeSpaceByLength.tailSet(new FreeSpace(0, lengthRequired));
          if (!tailSet.isEmpty()) {
              // Use free space in the body of file.
              freeSpace = (FreeSpace) tailSet.first();
              tailSet.remove(freeSpace);
  
              long remainingLength = freeSpace.length - lengthRequired;
  
              if (remainingLength < minimumFreeSpaceEntrySize) {
  
                  // All of this slot used up, also remove it from the address map.
                  if (freeSpace.prev != null) {
                      freeSpace.prev.next = freeSpace.next;
                  }
                  else {
                      freeSpaceByAddressHead = freeSpace.next;
                  }
                  if (freeSpace.next != null) {
                      freeSpace.next.prev = freeSpace.prev;
                  }
                  // Return without any links
                  freeSpace.prev = freeSpace.next = null;
  
                  // Debug freespace list
                  // if (Tracing.isAnyTracingEnabled() && trace.isDebugEnabled()) trace.debug(this, cclass, methodName, "REMOVE from freespace list");
  
              } else {
                  // Partially used, reduce the length, but leave it in place in the address Map.
                  // Allocate the end portion of the space found to a new FreeSpace area and  
                  // add the remaining piece back into the length map, where its key will have changed. 
                  freeSpace.length = remainingLength;
                  freeSpaceByLength.add(freeSpace);
  
                  freeSpace = new FreeSpace(freeSpace.address + remainingLength, lengthRequired);
              } // if (remainingLength == 0).
  
          } else {
              // Add to end of file.
              freeSpace = new FreeSpace(storeFileSizeUsed, lengthRequired);
              long newStoreFileSizeUsed = storeFileSizeUsed + lengthRequired;
              // Check to see if we need to extended the file. 
              if (newStoreFileSizeUsed > storeFileSizeAllocated) {
                  storeFileExtendedDuringAllocation++;
  
                  // This should not occur if we are using STRATEGY_KEEP_ALWAYS because we 
                  // have already allocated enough space to store all the objects currently
                  // in the log.
                  if (storeStrategy == STRATEGY_KEEP_ALWAYS
                      && (objectManagerState.logFileType == ObjectManager.LOG_FILE_TYPE_FILE
                      || objectManagerState.logFileType == ObjectManager.LOG_FILE_TYPE_CLEAR)) {
                      ObjectManager.ffdc.processException(this,
                                                          cclass,
                                                          methodName,
                                                          new Exception("Extended allocated file"),
                                                          "1:1437:1.57",
                                                          new Object[] { new Long(newStoreFileSizeUsed), new Long(storeFileSizeAllocated) });
                      if (Tracing.isAnyTracingEnabled() && trace.isDebugEnabled())
                          trace.debug(this, cclass, methodName, new Object[] { "STRATEGY_KEEP_ALWAYS:1440",
                                                                              new Long(newStoreFileSizeUsed),
                                                                              new Long(storeFileSizeAllocated) });
                  } // if ( objectManagerState.logFileType...
  
                  if (newStoreFileSizeUsed <= maximumStoreFileSize
                      && setStoreFileSizeInternal(newStoreFileSizeUsed)) {
  
                  } else {
                      allocationAllowed = false;
  
                      if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                          trace.exit(this,
                                     cclass,
                                     methodName,
                                     new Object[] { "ObjectStoreFull" });
                      throw new ObjectStoreFullException(this,
                                                         null);
                  }
              } // if (newStoreFileSizeUsed > storeFileSizeAllocated).
  
              storeFileSizeUsed = newStoreFileSizeUsed;
          } // if (!tailMap.isEmpty()).
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.exit(this,
                         cclass,
                         methodName,
                         new Object[] { freeSpace });
          return freeSpace;
      }