docs: public List.Entry addEntry(Token token,
                                 Transaction transaction)
                      throws ObjectManagerException
      {
          final String methodName = "addEntry";
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.entry(this, cclass, methodName, new Object[] { token,
                                                                  transaction });
  
          // This differs from the default ObjectManager
          // behaviour because we optimistically add the link to the list and may need to 
          // undo this if the transaction backs out. Simply restoring before immages is not
          // enough because we dont lock the list during the prepare phase and other links
          // could be chanied off this one and commit their trandsactions before
          // this one.
  
          Link newLink = null;
          // Take a lock on transaction then the list itself, this protects the structure of the list 
          // and prevents deadlock with threads backing out the transaction. During backout the list 
          // lock is traven in the preBackout call back after the transaction lock has been taken. 
          synchronized (transaction.internalTransaction) {
              synchronized (this) {
                  // Prevent other transactions using the list until its creation is commited.
                  if (!(state == stateReady)
                      && !((state == stateAdded) && lockedBy(transaction))) {
  
                      if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                          trace.exit(this, cclass, methodName, new Object[] { new Integer(state),
                                                                             stateNames[state] });
                      throw new InvalidStateException(this, state, stateNames[state]);
                  }
  
                  // All optimistic replace updates to links in the list must be made
                  // together, so we construct a single log record for all of them. 
                  managedObjectsToAdd.clear();
                  managedObjectsToReplace.clear();
                  reservedSpaceInStore = storeSpaceForAdd();
                  owningToken.objectStore.reserve((int) reservedSpaceInStore, false);
  
                  // Create the new link and add it to its object store.
                  newLink = new Link(this,
                                     token,
                                     tail,
                                     null,
                                     transaction);
                  managedObjectsToAdd.add(newLink);
  
                  // Chain the new Link in the list. If the transaction backs
                  // out we will rewrite the links to remove the new one.
                  if (head == null) // Only element in the list?
                  {
                      head = newLink.getToken();
                      availableHead = head; // PK75215
                  } else { // In the body of the list.
                      Link tailLink = (Link) tail.getManagedObject();
                      tailLink.next = newLink.getToken();
                      managedObjectsToReplace.add(tailLink);
                  }
                  tail = newLink.getToken();
  
                  incrementSize(); // Adjust list length assuming we will commit.
                  managedObjectsToReplace.add(this); // The anchor for the list.
  
                  // Harden the updates. If the update fails, because the log is full,
                  // we have affected the structure of the list so we will have to 
                  // reverse the changes. Reserve enough space to reverse the update if the
                  // transaction backs out.
                  // TODO We need another optimistic replace with a more restricted state machine, this one
                  // will allow an add after we have done prepare.
                  try {
                      transaction.optimisticReplace(managedObjectsToAdd,
                                                    managedObjectsToReplace,
                                                    null, // No tokens to delete.
                                                    null, // No tokens to notify.
                                                    +logSpaceForDelete());
                      // Give up reserved space, but keep back enough to remove the entry if we have to.
                      owningToken.objectStore.reserve((int) (storeSpaceForRemove() - reservedSpaceInStore), false);
  
                  } catch (InvalidStateException exception) {
                      // No FFDC Code Needed, user error.
                      // Remove the link we just added.
                      undoAdd(newLink);
  
                      if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                          trace.exit(this, cclass, methodName, exception);
                      throw exception;
  
                  } catch (LogFileFullException exception) {
                      // No FFDC Code Needed, InternalTransaction has already done this.
                      // Remove the link we just added.
                      undoAdd(newLink);
  
                      if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                          trace.exit(this, cclass, methodName, exception);
                      throw exception;
  
                      // We should not see ObjectStoreFullException because we have preReserved 
                      // the ObjectStore space.
  //        } catch (ObjectStoreFullException exception) {
  //          // No FFDC Code Needed, InternalTransaction has already done this.
  //          // Remove the link we just added.
  //          undoAdd(newLink);
  //          
  //          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
  //            trace.exit(this, cclass, methodName, exception);
  //          throw exception;
                  } // try.
  
              } // synchronized (this).
          } // synchronized (transaction.internalTransaction)
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.exit(this, cclass, methodName, new Object[] { newLink });
          return (List.Entry) newLink;
      }