From 42d99f90ca44935967b1a6970751007eb1b4ba5d Mon Sep 17 00:00:00 2001
From: Ray Greenwell <ray@threerings.net>
Date: Thu, 25 Feb 2010 23:17:06 +0000
Subject: [PATCH] Some language about the proper usage of Sequence.

---
 src/java/com/samskivert/depot/util/Sequence.java | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/java/com/samskivert/depot/util/Sequence.java b/src/java/com/samskivert/depot/util/Sequence.java
index baf5463..727401a 100644
--- a/src/java/com/samskivert/depot/util/Sequence.java
+++ b/src/java/com/samskivert/depot/util/Sequence.java
@@ -31,6 +31,11 @@ import com.google.common.base.Function;
  * Thus a caller is expected to either simply iterate over the elements once, or use {@link
  * #toList} to convert the sequence to concrete list to avoid repeated application of the
  * conversion function on elements of the sequence.
+ *
+ * Repository authors <i>may</i> want to return this interface for transformed findAll queries
+ * in order to avoid creating a second large List to contain elements. However, that exposes
+ * this interface to callers. The other two options are: go ahead and call toList() and return
+ * that to callers, or enforce single-iteration and return the result of iterator().
  */
 public interface Sequence<T> extends Iterable<T>
 {