docs: public void reorder()
      {
          int newOrderIndex = 0;
          long t1 = 0, t2 = 0, t3;
  
          if (log.isDebugEnabled())
          {
              t1 = System.currentTimeMillis();
          }
          newOrder = new Identity[originalOrder.size()];
  
          if(log.isDebugEnabled()) log.debug("Orginal order: " + originalOrder);
          // set up the vertex array in the order the envelopes were added
          List vertexList = new ArrayList(originalOrder.size());
          // int vertexIndex = 0;
          for (Iterator it = originalOrder.iterator(); it.hasNext();)
          {
              ObjectEnvelope envelope = (ObjectEnvelope) envelopes.get(it.next());
              if (envelope.needsUpdate() || envelope.needsInsert() || envelope.needsDelete())
              {
                  Vertex vertex = new Vertex(envelope);
                  vertexList.add(vertex);
                  if (log.isDebugEnabled())
                  {
                      log.debug("Add new Vertex object "+envelope.getIdentity()+" to VertexList");
                  }
              }
              else
              {
                  // envelope is clean - just add identity to new order
                  newOrder[newOrderIndex++] = envelope.getIdentity();
                  if (log.isDebugEnabled())
                  {
                      log.debug("Add unmodified object "+envelope.getIdentity()+" to new OrderList");
                  }
              }
          }
          vertices = (Vertex[]) vertexList.toArray(new Vertex[vertexList.size()]);
  
          // set up the edges
          edgeList = new ArrayList(2 * vertices.length);
          for (int i = 0; i < vertices.length; i++)
          {
              addEdgesForVertex(vertices[i]);
          }
  
          if (log.isDebugEnabled())
          {
              t2 = System.currentTimeMillis();
              log.debug("Building object envelope graph took " + (t2 - t1) + " ms");
              log.debug("Object envelope graph contains " + vertices.length + " vertices" + " and " + edgeList.size()
                      + " edges");
          }
  
          int remainingVertices = vertices.length;
          int iterationCount = 0;
          while (remainingVertices > 0)
          {
              // update iteration count
              iterationCount++;
  
              // update incoming edge counts
              for (Iterator it = edgeList.iterator(); it.hasNext();)
              {
                  Edge edge = (Edge) it.next();
                  if (!edge.isProcessed())
                  {
                      if(log.isDebugEnabled())
                      {
                          final String msg = "Add weight '"+edge.getWeight()+"' for terminal vertex " + edge.getTerminalVertex() + " of edge " + edge;
                          log.debug(msg);
                      }
                      edge.getTerminalVertex().incrementIncomingEdgeWeight(edge.getWeight());
                  }
              }
  
              // find minimum weight of incoming edges of a vertex
              int minIncomingEdgeWeight = Integer.MAX_VALUE;
              for (int i = 0; i < vertices.length; i++)
              {
                  Vertex vertex = vertices[i];
                  if (!vertex.isProcessed() && minIncomingEdgeWeight > vertex.getIncomingEdgeWeight())
                  {
                      minIncomingEdgeWeight = vertex.getIncomingEdgeWeight();
                      if (minIncomingEdgeWeight == 0)
                      {
                          // we won't get any lower
                          break;
                      }
                  }
              }
  
              // process vertices having minimum incoming edge weight
              int processCount = 0;
              for (int i = 0; i < vertices.length; i++)
              {
                  Vertex vertex = vertices[i];
                  if (!vertex.isProcessed() && vertex.getIncomingEdgeWeight() == minIncomingEdgeWeight)
                  {
                      newOrder[newOrderIndex++] = vertex.getEnvelope().getIdentity();
                      vertex.markProcessed();
                      processCount++;
                      if (log.isDebugEnabled())
                      {
                          log.debug("add minimum edge weight - "+minIncomingEdgeWeight
                                  + ", newOrderList: " + ArrayUtils.toString(newOrder));
                      }
                  }
                  vertex.resetIncomingEdgeWeight();
              }
  
              if (log.isDebugEnabled())
              {
                  log.debug("Processed " + processCount + " of " + remainingVertices
                          + " remaining vertices in iteration #" + iterationCount);
              }
              remainingVertices -= processCount;
          }
  
          if (log.isDebugEnabled())
          {
              t3 = System.currentTimeMillis();
              log.debug("New ordering: " + ArrayUtils.toString(newOrder));
              log.debug("Processing object envelope graph took " + (t3 - t2) + " ms");
          }
  
      }