DATADOC-24 - Refactored SimpleParameterAccessor to improve usability.

Extracted ParameterAccessor interface that uses a simple Iterator<Object> to traverse over bindable parameters. Renamed SimpleParameterAccessor to ParametersParameterAccessor to better reflect its specialty (improved JavaDoc according to this as well).

spring-data-commons-core/src/main/java/org/springframework/data/repository/query/ParameterAccessor.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2011 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.repository.query;
+
+import java.util.Iterator;
+
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.domain.Sort;
+
+
+/**
+ * Interface to access method parameters. Allows dedicated access to parameters
+ * of special types
+ * 
+ * @author Oliver Gierke
+ */
+public interface ParameterAccessor extends Iterable<Object> {
+
+    /**
+     * Returns the {@link Pageable} of the parameters, if available. Returns
+     * {@code null} otherwise.
+     * 
+     * @return
+     */
+    Pageable getPageable();
+
+
+    /**
+     * Returns the sort instance to be used for query creation. Will use a
+     * {@link Sort} parameter if available or the {@link Sort} contained in a
+     * {@link Pageable} if available. Returns {@code null} if no {@link Sort}
+     * can be found.
+     * 
+     * @return
+     */
+    Sort getSort();
+
+
+    /**
+     * Returns an iterator over all <em>bindable</em> parameters. This means
+     * parameters implementing {@link Pageable} or {@link Sort} will not be
+     * included in this {@link Iterator}.
+     * 
+     * @return
+     */
+    Iterator<Object> iterator();
+}

spring-data-commons-core/src/main/java/org/springframework/data/repository/query/ParametersParameterAccessor.java

@@ -15,29 +15,32 @@
  */
 package org.springframework.data.repository.query;
 
+import java.util.Iterator;
+
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.util.Assert;
 
 
 /**
- * {@link SimpleParameterAccessor} is used to bind method parameters.
+ * {@link ParameterAccessor} implementation using a {@link Parameters} instance
+ * to find special parameters.
  * 
  * @author Oliver Gierke
  */
-public class SimpleParameterAccessor {
+public class ParametersParameterAccessor implements ParameterAccessor {
 
     private final Parameters parameters;
     private final Object[] values;
 
 
     /**
-     * Creates a new {@link SimpleParameterAccessor}.
+     * Creates a new {@link ParametersParameterAccessor}.
      * 
      * @param parameters
      * @param values
      */
-    public SimpleParameterAccessor(Parameters parameters, Object[] values) {
+    public ParametersParameterAccessor(Parameters parameters, Object[] values) {
 
         Assert.notNull(parameters);
         Assert.notNull(values);
@@ -50,11 +53,11 @@ public class SimpleParameterAccessor {
     }
 
 
-    /**
-     * Returns the {@link Pageable} of the parameters, if available. Returns
-     * {@code null} otherwise.
+    /*
+     * (non-Javadoc)
      * 
-     * @return
+     * @see
+     * org.springframework.data.repository.query.ParameterAccessor#getPageable()
      */
     public Pageable getPageable() {
 
@@ -66,13 +69,11 @@ public class SimpleParameterAccessor {
     }
 
 
-    /**
-     * Returns the sort instance to be used for query creation. Will use a
-     * {@link Sort} parameter if available or the {@link Sort} contained in a
-     * {@link Pageable} if available. Returns {@code null} if no {@link Sort}
-     * can be found.
+    /*
+     * (non-Javadoc)
      * 
-     * @return
+     * @see
+     * org.springframework.data.repository.query.ParameterAccessor#getSort()
      */
     public Sort getSort() {
 
@@ -94,11 +95,11 @@ public class SimpleParameterAccessor {
     }
 
 
-    /**
-     * Returns a {@link BindableParameterIterator} to traverse all bindable
-     * parameters.
+    /*
+     * (non-Javadoc)
      * 
-     * @return
+     * @see
+     * org.springframework.data.repository.query.ParameterAccessor#iterator()
      */
     public BindableParameterIterator iterator() {
 
@@ -111,7 +112,7 @@ public class SimpleParameterAccessor {
      * 
      * @author Oliver Gierke
      */
-    public class BindableParameterIterator {
+    private class BindableParameterIterator implements Iterator<Object> {
 
         private int currentIndex = 0;
 
@@ -125,5 +126,27 @@ public class SimpleParameterAccessor {
 
             return getBindableValue(currentIndex++);
         }
+
+
+        /*
+         * (non-Javadoc)
+         * 
+         * @see java.util.Iterator#hasNext()
+         */
+        public boolean hasNext() {
+
+            return values.length <= currentIndex;
+        }
+
+
+        /*
+         * (non-Javadoc)
+         * 
+         * @see java.util.Iterator#remove()
+         */
+        public void remove() {
+
+            throw new UnsupportedOperationException();
+        }
     }
 }

spring-data-commons-core/src/main/java/org/springframework/data/repository/query/parser/AbstractQueryCreator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2008-2010 the original author or authors.
+ * Copyright 2008-2011 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,9 +15,11 @@
  */
 package org.springframework.data.repository.query.parser;
 
+import java.util.Iterator;
+
 import org.springframework.data.domain.Sort;
-import org.springframework.data.repository.query.SimpleParameterAccessor;
-import org.springframework.data.repository.query.SimpleParameterAccessor.BindableParameterIterator;
+import org.springframework.data.repository.query.ParameterAccessor;
+import org.springframework.data.repository.query.ParametersParameterAccessor;
 import org.springframework.data.repository.query.parser.PartTree.OrPart;
 import org.springframework.util.Assert;
 
@@ -32,19 +34,18 @@ import org.springframework.util.Assert;
  */
 public abstract class AbstractQueryCreator<T, S> {
 
-    private final SimpleParameterAccessor parameters;
+    private final ParameterAccessor parameters;
     private final PartTree tree;
 
 
     /**
      * Creates a new {@link AbstractQueryCreator} for the given {@link PartTree}
-     * and {@link SimpleParameterAccessor}.
+     * and {@link ParametersParameterAccessor}.
      * 
      * @param tree
      * @param parameters
      */
-    public AbstractQueryCreator(PartTree tree,
-            SimpleParameterAccessor parameters) {
+    public AbstractQueryCreator(PartTree tree, ParameterAccessor parameters) {
 
         Assert.notNull(tree);
         Assert.notNull(parameters);
@@ -75,7 +76,7 @@ public abstract class AbstractQueryCreator<T, S> {
     private S createCriteria(PartTree tree) {
 
         S base = null;
-        BindableParameterIterator iterator = parameters.iterator();
+        Iterator<Object> iterator = parameters.iterator();
 
         for (OrPart node : tree) {
 
@@ -102,7 +103,7 @@ public abstract class AbstractQueryCreator<T, S> {
      * @param iterator
      * @return
      */
-    protected abstract S create(Part part, BindableParameterIterator iterator);
+    protected abstract S create(Part part, Iterator<Object> iterator);
 
 
     /**
@@ -114,8 +115,7 @@ public abstract class AbstractQueryCreator<T, S> {
      * @param iterator
      * @return
      */
-    protected abstract S and(Part part, S base,
-            BindableParameterIterator iterator);
+    protected abstract S and(Part part, S base, Iterator<Object> iterator);
 
 
     /**

spring-data-commons-core/src/test/java/org/springframework/data/repository/query/SimpleParameterAccessorUnitTests.java

@@ -26,7 +26,7 @@ import org.springframework.data.domain.Sort;
 
 
 /**
- * Unit tests for {@link SimpleParameterAccessor}.
+ * Unit tests for {@link ParametersParameterAccessor}.
  * 
  * @author Oliver Gierke
  */
@@ -52,43 +52,43 @@ public class SimpleParameterAccessorUnitTests {
     @Test
     public void testname() throws Exception {
 
-        new SimpleParameterAccessor(parameters, new Object[] { "test" });
+        new ParametersParameterAccessor(parameters, new Object[] { "test" });
     }
 
 
     @Test(expected = IllegalArgumentException.class)
     public void rejectsNullParameters() throws Exception {
 
-        new SimpleParameterAccessor(null, new Object[0]);
+        new ParametersParameterAccessor(null, new Object[0]);
     }
 
 
     @Test(expected = IllegalArgumentException.class)
     public void rejectsNullValues() throws Exception {
 
-        new SimpleParameterAccessor(parameters, null);
+        new ParametersParameterAccessor(parameters, null);
     }
 
 
     @Test(expected = IllegalArgumentException.class)
     public void rejectsTooLittleNumberOfArguments() throws Exception {
 
-        new SimpleParameterAccessor(parameters, new Object[0]);
+        new ParametersParameterAccessor(parameters, new Object[0]);
     }
 
 
     @Test(expected = IllegalArgumentException.class)
     public void rejectsTooManyArguments() throws Exception {
 
-        new SimpleParameterAccessor(parameters, new Object[] { "test", "test" });
+        new ParametersParameterAccessor(parameters, new Object[] { "test", "test" });
     }
 
 
     @Test
     public void returnsNullForPageableAndSortIfNoneAvailable() throws Exception {
 
-        SimpleParameterAccessor accessor =
-                new SimpleParameterAccessor(parameters, new Object[] { "test" });
+        ParameterAccessor accessor =
+                new ParametersParameterAccessor(parameters, new Object[] { "test" });
         assertThat(accessor.getPageable(), is(nullValue()));
         assertThat(accessor.getSort(), is(nullValue()));
     }
@@ -98,8 +98,8 @@ public class SimpleParameterAccessorUnitTests {
     public void returnsSortIfAvailable() {
 
         Sort sort = new Sort("foo");
-        SimpleParameterAccessor accessor =
-                new SimpleParameterAccessor(sortParameters, new Object[] {
+        ParameterAccessor accessor =
+                new ParametersParameterAccessor(sortParameters, new Object[] {
                         "test", sort });
         assertThat(accessor.getSort(), is(sort));
         assertThat(accessor.getPageable(), is(nullValue()));
@@ -110,8 +110,8 @@ public class SimpleParameterAccessorUnitTests {
     public void returnsPageableIfAvailable() {
 
         Pageable pageable = new PageRequest(0, 10);
-        SimpleParameterAccessor accessor =
-                new SimpleParameterAccessor(pageableParameters, new Object[] {
+        ParameterAccessor accessor =
+                new ParametersParameterAccessor(pageableParameters, new Object[] {
                         "test", pageable });
         assertThat(accessor.getPageable(), is(pageable));
         assertThat(accessor.getSort(), is(nullValue()));
@@ -123,8 +123,8 @@ public class SimpleParameterAccessorUnitTests {
 
         Sort sort = new Sort("foo");
         Pageable pageable = new PageRequest(0, 10, sort);
-        SimpleParameterAccessor accessor =
-                new SimpleParameterAccessor(pageableParameters, new Object[] {
+        ParameterAccessor accessor =
+                new ParametersParameterAccessor(pageableParameters, new Object[] {
                         "test", pageable });
         assertThat(accessor.getPageable(), is(pageable));
         assertThat(accessor.getSort(), is(sort));