Add getList methods to the Document class

JAVA-1720

Author: jstewart148

bson/src/main/org/bson/Document.java

@@ -33,9 +33,11 @@
 import java.util.Collection;
 import java.util.Date;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
+import static java.lang.String.format;
 import static org.bson.assertions.Assertions.notNull;
 
 /**
@@ -259,6 +261,58 @@ public Date getDate(final Object key) {
         return (Date) get(key);
     }
 
+    /**
+     * Gets the list value of the given key, casting the list elements to the given {@code Class<T>}.  This is useful to avoid having
+     * casts in client code, though the effect is the same.
+     *
+     * @param key   the key
+     * @param clazz the non-null class to cast the list value to
+     * @param <T>   the type of the class
+     * @return the list value of the given key, or null if the instance does not contain this key.
+     * @throws ClassCastException if the elements in the list value of the given key is not of type T or the value is not a list
+     * @since 3.10
+     */
+    public <T> List<T> getList(final Object key, final Class<T> clazz) {
+        notNull("clazz", clazz);
+        return constructValuesList(key, clazz, null);
+    }
+
+    /**
+     * Gets the list value of the given key, casting the list elements to {@code Class<T>} or returning the default list value if null.
+     * This is useful to avoid having casts in client code, though the effect is the same.
+     *
+     * @param key   the key
+     * @param clazz the non-null class to cast the list value to
+     * @param defaultValue what to return if the value is null
+     * @param <T>   the type of the class
+     * @return the list value of the given key, or the default list value if the instance does not contain this key.
+     * @throws ClassCastException if the value of the given key is not of type T
+     * @since 3.10
+     */
+    public <T> List<T> getList(final Object key, final Class<T> clazz, final List<T> defaultValue) {
+        notNull("defaultValue", defaultValue);
+        notNull("clazz", clazz);
+        return constructValuesList(key, clazz, defaultValue);
+    }
+
+
+    // Construct the list of values for the specified key, or return the default value if the value is null.
+    // A ClassCastException will be thrown if an element in the list is not of type T.
+    @SuppressWarnings("unchecked")
+    private <T> List<T> constructValuesList(final Object key, final Class<T> clazz, final List<T> defaultValue) {
+        List<?> value = get(key, List.class);
+        if (value == null) {
+            return defaultValue;
+        }
+
+        for (Object item : value) {
+            if (!clazz.isAssignableFrom(item.getClass())) {
+                throw new ClassCastException(format("List element cannot be cast to %s", clazz.getName()));
+            }
+        }
+        return (List<T>) value;
+    }
+
     /**
      * Gets a JSON representation of this document using the {@link org.bson.json.JsonMode#STRICT} output mode, and otherwise the default
      * settings of {@link JsonWriterSettings.Builder} and {@link DocumentCodec}.

bson/src/test/unit/org/bson/types/DocumentSpecification.groovy

@@ -65,6 +65,67 @@ class DocumentSpecification extends Specification {
         doc.get('noVal', objectId) == objectId
     }
 
+    def 'should return a list with elements of the specified class'() {
+        when:
+        Document doc = Document.parse("{x: 1, y: ['two', 'three'], z: [{a: 'one'}, {b:2}], w: {a: ['One', 'Two']}}")
+                .append('numberList', Arrays.asList(10, 20.5d, 30L))
+        List<String> defaultList = Arrays.asList('a', 'b', 'c')
+
+        then:
+        doc.getList('y', String).get(0) == 'two'
+        doc.getList('y', String).get(1) == 'three'
+        doc.getList('z', Document).get(0).getString('a') == 'one'
+        doc.getList('z', Document).get(1).getInteger('b') == 2
+        doc.get('w', Document).getList('a', String).get(0) == 'One'
+        doc.get('w', Document).getList('a', String).get(1) == 'Two'
+        doc.getList('invalidKey', Document, defaultList).get(0) == 'a'
+        doc.getList('invalidKey', Document, defaultList).get(1) == 'b'
+        doc.getList('invalidKey', Document, defaultList).get(2) == 'c'
+        doc.getList('numberList', Number).get(0) == 10
+        doc.getList('numberList', Number).get(1) == 20.5d
+        doc.getList('numberList', Number).get(2) == 30L
+    }
+
+    def 'should return null list when key is not found'() {
+        when:
+        Document doc = Document.parse('{x: 1}')
+
+        then:
+        doc.getList('a', String) == null
+    }
+
+    def 'should return specified default value when key is not found'() {
+        when:
+        Document doc = Document.parse('{x: 1}')
+        List<String> defaultList = Arrays.asList('a', 'b', 'c')
+
+        then:
+        doc.getList('a', String, defaultList) == defaultList
+    }
+
+    def 'should throw an exception when the list elements are not objects of the specified class'() {
+        given:
+        Document doc = Document.parse('{x: 1, y: [{a: 1}, {b: 2}], z: [1, 2]}')
+
+        when:
+        doc.getList('x', String)
+
+        then:
+        thrown(ClassCastException)
+
+        when:
+        doc.getList('y', String)
+
+        then:
+        thrown(ClassCastException)
+
+        when:
+        doc.getList('z', String)
+
+        then:
+        thrown(ClassCastException)
+    }
+
     def 'should parse a valid JSON string to a Document'() {
         when:
         Document document = Document.parse("{ 'int' : 1, 'string' : 'abc' }");