Allow ObjectReuseAsIs to resort objects during writing

It can be very handy for the implementation to resort the
object list based on data locality, improving prefetch in
the operating system's buffer cache.

Export the list to the implementation was a proper List,
and document that its mutable and OK to be modified.  The
only caller in PackWriter is already OK with these rules.

Change-Id: I3f51cf4388898917b2be36670587a5aee902ff10
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCursor.java

@@ -48,6 +48,7 @@ import java.io.IOException;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.HashSet;
+import java.util.List;
 import java.util.zip.DataFormatException;
 import java.util.zip.Inflater;
 
@@ -147,7 +148,7 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs {
 		src.pack.copyAsIs(out, src, this);
 	}
 
-	public void writeObjects(PackOutputStream out, Iterable<ObjectToPack> list)
+	public void writeObjects(PackOutputStream out, List<ObjectToPack> list)
 			throws IOException {
 		for (ObjectToPack otp : list)
 			out.writeObject(otp);

org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/ObjectReuseAsIs.java

@@ -44,6 +44,7 @@
 package org.eclipse.jgit.storage.pack;
 
 import java.io.IOException;
+import java.util.List;
 
 import org.eclipse.jgit.errors.MissingObjectException;
 import org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException;
@@ -135,12 +136,13 @@ public interface ObjectReuseAsIs {
 	 *            the stream to write each object to.
 	 * @param list
 	 *            the list of objects to write. Objects should be written in
-	 *            approximately this order.
+	 *            approximately this order. Implementors may resort the list
+	 *            elements in-place during writing if desired.
 	 * @throws IOException
 	 *             the stream cannot be written to, or one or more required
 	 *             objects cannot be accessed from the object database.
 	 */
-	public void writeObjects(PackOutputStream out, Iterable<ObjectToPack> list)
+	public void writeObjects(PackOutputStream out, List<ObjectToPack> list)
 			throws IOException;
 
 	/**