Comment updates.

2 files changed, 11 insertions, 8 deletions

diff --git a/src/main/java/com/amazon/carbonado/Query.java b/src/main/java/com/amazon/carbonado/Query.java
index 6073a84..e27e484 100644
--- a/src/main/java/com/amazon/carbonado/Query.java
+++ b/src/main/java/com/amazon/carbonado/Query.java
@@ -24,15 +24,16 @@ import com.amazon.carbonado.filter.Filter;
 import com.amazon.carbonado.filter.FilterValues;

 

 /**

- * Supports complex retrieval and deletion of {@link Storable} objects. A Query

- * is defined by {@link Storage#query}, and it merely represents an action. It

- * does not contain any data, and it is immutable. Query objects are usually

- * compiled and cached, and the same instance can be re-used for future

- * queries.

+ * Supports complex retrieval and deletion of {@link Storable} objects.

+ * Queries are immutable representations of an action \u2013 they do not

+ * contain any Storable instances. The apparent mutators (with, et al) do not

+ * actually modify the Query. Instead, they return another Query instance which

+ * has the requested modification. To obtain an initial Query instance, call

+ * one of the {@link Storage} query methods.

  *

- * <p>Query instances are thread-safe and immutable. All of the apparent

- * mutators (with, et al) do not modify the Query, but instead return a new

- * Query with the requested modification.

+ * <p>Query objects are usually compiled and cached, and the same instance can

+ * be re-used for future queries. This is possible because queries are

+ * immutable and naturally thread-safe.

  *

  * @author Brian S O'Neill

  */

diff --git a/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java b/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java
index d306e25..25423ee 100644
--- a/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java
+++ b/src/main/java/com/amazon/carbonado/qe/IndexedQueryExecutor.java
@@ -395,6 +395,7 @@ public class IndexedQueryExecutor<S extends Storable> extends AbstractQueryExecu
          * never called by IndexedQueryExecutor.

          *

          * @return index entry query or null if not supported

+         * @since 1.2

          */

         Query<?> indexEntryQuery(StorableIndex<S> index) throws FetchException;

 

@@ -405,6 +406,7 @@ public class IndexedQueryExecutor<S extends Storable> extends AbstractQueryExecu
          * @param index index to open

          * @param indexEntryQuery query with no blank parameters, derived from

          * the query returned by indexEntryQuery

+         * @since 1.2

          */

         Cursor<S> fetchFromIndexEntryQuery(StorableIndex<S> index, Query<?> indexEntryQuery)

             throws FetchException;