docs: protected void setLogFileSize(long newFileSize)
                      throws ObjectManagerException
      {
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.entry(this, cclass
                          , "setLogFileSize"
                          , "newFileSize=" + newFileSize + "(long)"
                              );
  
          // Note where we are in the log file.
          long initialFilePosition = filePosition;
  
          synchronized (newFileSizeRequestLock) {
              // Force the new file size to be a whole number of pages.
              this.newFileSize = (newFileSize / pageSize) * pageSize;
              newFileSizeRequested = true;
              newFileSizeException = null;
              logFileSizeRequested = newFileSize;
              // We have not yet seen the log file wrap.
              boolean wrapped = false;
  
              // Keep requesting checkpoints until the start and end of the log data are both 
              // before the new end of the log, without the user log data wrapping round the 
              // end of the logFile.
              while (newFileSizeRequested) {
  
                  // Check there is still some chance of fitting the current log into the new one.
                  // and that we have not wrapped round the log file without succeeding.
                  long fileSpaceAvailable = getLogFileSpaceLeft();
                  long newFileSpaceAvailable = fileSpaceAvailable - fileLogHeader.fileSize + newFileSize;
                  float newOcupancy = (float) 1.0 - (float) (newFileSpaceAvailable) / (float) (newFileSize);
                  if (newOcupancy > objectManagerState.logFullPostCheckpointThreshold
                      || wrapped) {
                      newFileSizeRequested = false;
                      logFileSizeRequested = 0;
                      if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                          trace.exit(this,
                                     cclass,
                                     "setLogFileSize",
                                     new Object[] { new Long(fileLogHeader.fileSize),
                                                   new Long(newFileSize),
                                                   new Float(newOcupancy) });
                      throw new LogFileSizeTooSmallException(this
                                                             , fileLogHeader.fileSize
                                                             , newFileSize
                                                             , fileSpaceAvailable
                                                             , newOcupancy
                                                             , objectManagerState.logFullPostCheckpointThreshold);
                  } // if (   (fileSpaceLeft...
  
                  if (Tracing.isAnyTracingEnabled() && trace.isDebugEnabled())
                      trace.debug(this,
                                  cclass,
                                  "setLogFileSize",
                                  new Object[] { new Long(filePosition),
                                                new Long(initialFilePosition) });
  
                  // If we have wrapped round the log file, give up after the next attempt to satisfy the 
                  // request. 
                  if (filePosition < initialFilePosition)
                      wrapped = true;
  
                  // We have released the lock on writingFlushSet set so now we can request a checkpoint and
                  // see if we are successful.
                  objectManagerState.waitForCheckpoint(true);
  
                  // Speed up moving the filePosition by writing a reasonable ammount of data.
                  // The folowing is dangerous because it can cause the request to fail if we 
                  // are trying to reduce the log file size close to the minimum possible. 
  //        PaddingLogRecord paddingLogRecord = new PaddingLogRecord(logBufferSize/2);
  //        writeNext(paddingLogRecord
  //                 ,0
  //                 ,true
  //                 );
  
              } // while (newFileSizeRequested...
  
              logFileSizeRequested = 0;
          } // synchronized (newFileSizeRequestLock).                                            
  
          if (newFileSizeException != null) {
              if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                  trace.exit(this, cclass
                             , "setLogFileSize"
                             , "via PermanentIOException newFileSizeException=" + newFileSizeException + "(PermanentIOException)"
                                  );
              throw newFileSizeException;
          }
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.exit(this, cclass
                         , "setLogFileSize"
                              );
      }