docs: public Token allocate(ManagedObject objectToStore)
                      throws ObjectManagerException
      {
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.entry(this,
                          cclass,
                          "allocate",
                          objectToStore);
  
          // We cannot store null, it won't serialize and we have no way to manage the transaction state.
          if (objectToStore == null) {
              if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                  trace.exit(this,
                             cclass,
                             "allocate",
                             objectToStore);
              throw new InvalidObjectToStoreException(this,
                                                      objectToStore);
          } // If asked to store null.
  
          // Is the store full?
          if (!allocationAllowed) {
              // request or wait for a checkpoint and see if that helps
              if (getStoreFullWaitForCheckPoint())
              {
                  if (trace.isDebugEnabled())
                      trace.debug(this, cclass, "allocate", "Store is currently full, waiting for checkpoint");
                  objectManagerState.waitForCheckpoint(true);
              }
              else
              {
                  if (trace.isDebugEnabled())
                      trace.debug(this, cclass, "allocate", "Store is currently full, requesting checkpoint");
                  objectManagerState.requestCheckpoint(true);
              }
  
              if (!allocationAllowed)
              {
                  if (trace.isEntryEnabled())
                      trace.exit(this, cclass
                                 , "allocate"
                                      );
  
                  throw new ObjectStoreFullException(this
                                                     , objectToStore);
              }
          } // If (!allocationAllowed). 
  
          Token tokenToStore;
          long usableSequenceNumber;
  
          synchronized (sequenceNumberLock) {
              // Establish the sequence number we will use. 
              usableSequenceNumber = ++sequenceNumber;
          } // synchronized (sequenceNumberLock).
  
          // Create the container for the object.    
          tokenToStore = new Token(objectToStore, this, usableSequenceNumber);
  
          // Keep a note of the in memory copy of the object so that we give back the same one
          // whenever it is asked for.
          // If the application never adds the object, we would clean this up when its reference to the Object
          // is lost. 
          Token inMemoryToken = (Token) inMemoryTokens.putIfAbsent(new Long(usableSequenceNumber),
                                                                   tokenToStore);
  
          // Check that this genuinely a new storedObjectIdentifier.
          if (inMemoryToken != null) {
              if (Tracing.isAnyTracingEnabled() && trace.isDebugEnabled())
                  trace.debug(this,
                              cclass,
                              "allocate",
                              new Object[] { "via StoreSequenceException",
                                            inMemoryToken,
                                            new Long(sequenceNumber) });
              StoreSequenceException storeSequenceException = new StoreSequenceException(this,
                                                                                         sequenceNumber,
                                                                                         inMemoryToken);
              ObjectManager.ffdc.processException(this,
                                                  cclass,
                                                  "add",
                                                  storeSequenceException,
                                                  "1:402:1.31");
              if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
                  trace.exit(this,
                             cclass,
                             "allocate",
                             storeSequenceException);
              throw storeSequenceException;
          } // if (inMemoryToken != null).
  
          if (Tracing.isAnyTracingEnabled() && trace.isEntryEnabled())
              trace.exit(this, cclass
                         , "allocate"
                         , new Object[] { tokenToStore }
                              );
          return tokenToStore;
      }