fix #437 - fix support for Date range queries, with unit test and javadocs; upgrade to latest Jackson

(cherry picked from commit b096a85)

Author: sammefford

pom.xml

@@ -288,17 +288,17 @@
 		<dependency>
 			<groupId>com.fasterxml.jackson.core</groupId>
 			<artifactId>jackson-core</artifactId>
-			<version>2.4.1</version>
+			<version>2.8.3</version>
 		</dependency>
 		<dependency>
 			<groupId>com.fasterxml.jackson.core</groupId>
 			<artifactId>jackson-annotations</artifactId>
-			<version>2.4.1</version>
+			<version>2.8.3</version>
 		</dependency>
 		<dependency>
 			<groupId>com.fasterxml.jackson.core</groupId>
 			<artifactId>jackson-databind</artifactId>
-			<version>2.4.1</version>
+			<version>2.8.3</version>
 		</dependency>
 		<!-- test dependencies -->
 		<dependency>
@@ -359,13 +359,13 @@
 		<dependency>
 			<groupId>com.fasterxml.jackson.dataformat</groupId>
 			<artifactId>jackson-dataformat-xml</artifactId>
-			<version>2.4.1</version>
+			<version>2.8.3</version>
 			<scope>test</scope>
 		</dependency>
 		<dependency>
 			<groupId>com.fasterxml.jackson.dataformat</groupId>
 			<artifactId>jackson-dataformat-csv</artifactId>
-			<version>2.4.1</version>
+			<version>2.8.3</version>
 			<scope>test</scope>
 		</dependency>
 	</dependencies>

src/main/java/com/marklogic/client/impl/PojoQueryBuilderImpl.java

@@ -17,6 +17,7 @@
 
 import java.lang.reflect.Method;
 import java.lang.reflect.Modifier;
+import java.util.Calendar;
 import java.util.Date;
 import java.util.HashMap;
 
@@ -245,6 +246,8 @@ public String getRangeIndexType(String propertyName) {
                 type = "xs:decimal";
             } else if ( Date.class.isAssignableFrom(propertyClass) ) {
                 type = "xs:dateTime";
+            } else if ( Calendar.class.isAssignableFrom(propertyClass) ) {
+                type = "xs:dateTime";
             }
             if ( type == null ) {
                 throw new IllegalArgumentException("Property " + propertyName + " is not a native Java type");

src/main/java/com/marklogic/client/pojo/PojoRepository.java

@@ -25,11 +25,12 @@
 
 import java.io.Serializable;
 
-/** PojoRepository is the central class for the Pojo Facade.  It supports CRUD operations
+/** <p>PojoRepository is the central class for the Pojo Facade.  It supports CRUD operations
  * and search.  Each PojoRepository instance operates on only one pojo class.  Create new
- * PojoRepository instances based on your custom pojo type like so:
+ * PojoRepository instances based on your custom pojo type like so:</p>
+ *
  * <pre>    public class MyClass {
- *        {@literal @}Id
+ *       {@literal @}Id
  *        public Integer getMyId() {
  *            ...
  *        }
@@ -43,47 +44,74 @@
  *    PojoRepository&lt;MyClass, Integer&gt; myClassRepo = 
  *        client.newPojoRepository(MyClass.class, Integer.class);</pre>
  *
- * Where MyClass is your custom pojo type, and myId is the bean property of type Integer
+ * <p>Where MyClass is your custom pojo type, and myId is the bean property of type Integer
  * marked with the 
  * {@literal @}{@link Id Id annotation}.  The 
  * {@literal @}Id annotation can be attached to a public field or a public getter or a 
  * public setter.  The bean property marked with {@literal @}Id must be a native type or 
  * {@link java.io.Serializable} class and must contain an 
  * identifier value unique across all persisted instances of that
- * type or the instance will overwrite the persisted instance with the same identifier.
+ * type or the instance will overwrite the persisted instance with the same identifier.</p>
+ *
+ * <p>The current implementation of the Pojo Facade uses 
+ * <a href="https://github.com/FasterXML/jackson-databind/">Jackson databind</a>
+ * for serialization and deserialization to and from json.  Thus only classes which
+ * can be serialized and deserialized directly by Jackson can be serialized by the
+ * Pojo Facade.  Every bean property including the one marked with {@literal @}Id
+ * must either expose a public field or both a public getter and a public
+ * setter.  To test if your class can be directly serialized and deserialized
+ * by Jackson, perform the following:</p>
  *
- * The current implementation of the Pojo Facade uses 
- * <a href="https://github.com/FasterXML/jackson-databind/">Jackson databind</a> for serialization
- * and deserialization to json.  Thus only classes which can be serialized and deserialized 
- * directly by Jackson can be serialized by the Pojo Facade.  Every bean property
- * including the one marked with {@literal @}Id must either expose a public field or both a public 
- * getter and a public setter.  To test if your class can be directly serialized and 
- * deserialized by Jackson, perform the following:
  * <pre>    ObjectMapper objectMapper = new ObjectMapper();
  *    String value = objectMapper.writeValueAsString(myObjectIn);
  *    MyClass myObjectOut = objectMapper.readValue(value, MyClass.class);</pre>
  *
- * If that works but the configured objectMapper in the Pojo Facade is different and not
- * working, you can troubleshoot by directly accessing the objectMapper used by the Pojo 
- * Facade using an unsupported internal method attached to the current implementation: 
- * <a 
+ * <p>If that works but the configured objectMapper in the Pojo Facade is different and not
+ * working, you can troubleshoot by directly accessing the objectMapper used by the Pojo
+ * Facade using an unsupported internal method attached to the current implementation:
+ * <a
  * href="https://github.com/marklogic/java-client-api/blob/master/src/main/java/com/marklogic/client/impl/PojoRepositoryImpl.java"
- * >com.marklogic.client.impl.PojoRepositoryImpl</a>.
+ * >com.marklogic.client.impl.PojoRepositoryImpl</a>.</p>
+ *
  * <pre>    ObjectMapper objectMapper = ((PojoRepositoryImpl) myClassRepo).getObjectMapper();</pre>
  *
- * If your class has properties which are classes (non-native types) they will be automatically 
- * serialized and deserialized, but cannot be written, read, or searched directly.  If you 
- * wish to directly write, read, or search another class, create a new instance of 
- * PojoRepository specific to that class.
+ * <p>Special handling is provided for bean properties of type
+ * {@link java.util.Date Date} and {@link java.util.Calendar Calendar}.  The
+ * current implementation of Jackson ObjectMapper changes the timezone to UTC.
+ * The serialized format is ISO 8601 format which is compatible with
+ * xs:dateTime format and can therefore be indexed in the server by a path
+ * range index of type dateTime.  However, if you wish to query using a range
+ * index, it is recommended that you modify serialization to remove the class
+ * wrapper by adding a JsonTypeInfo annotation like so:</p>
+ *
+ * <pre>   {@literal @}JsonTypeInfo(use=JsonTypeInfo.Id.NONE, include=JsonTypeInfo.As.EXTERNAL_PROPERTY)
+ *    public Calendar getMyDateTime();</pre>
+ *
+ * <p>That way you can query the field directly without needing to traverse the
+ * java.util.GregorianCalendar type wrapper.  By removing that wrapper, you can
+ * create a query like this:</p>
+ *
+ * <pre>    PojoQueryBuilder qb = pojoRepository.getQueryBuilder();
+ *    PojoQueryDefinition query = qb.range("myDateTime", Operator.LT, Calendar.getInstance());</pre>
+ *
+ * <p>If your class has properties which are classes (non-native types) they
+ * will be automatically serialized and deserialized, but can only be written,
+ * read, or searched as properties of the parent instance.  If you wish to
+ * directly write, read, or search instances of another class, create and use
+ * an instance of PojoRepository specific to that class.</p>
  *
- * Since PojoRepository stores in JSON format, which limits number precision to 15
- * significant digits (IEEE754 double precision), you will lose precision on numbers
- * longer than 15 significant digits.  If you desire larger numbers with no loss of
- * precision, use Strings to persist those numbers.
+ * <p>Since PojoRepository stores in JSON format, which limits number precision
+ * to 15 significant digits (IEEE754 double precision), you will lose precision
+ * on numbers longer than 15 significant digits.  If you desire larger numbers
+ * with no loss of precision, use Strings to persist those numbers.</p>
  */
 public interface PojoRepository<T, ID extends Serializable> {
-    /** Get the value of the id field (the field marked with the {@literal @}Id 
+    /** Get the value of the id field (the field marked with the {@literal @}Id
      * annotation).
+     *
+     * @param entity the entity instance from which you want to get the id value
+     *
+     * @return the id value for this entity of type ID
      */
     public ID getId(T entity);
 

src/main/java/com/marklogic/client/query/StructuredQueryBuilder.java

@@ -21,6 +21,7 @@
 import java.io.StringReader;
 import java.io.StringWriter;
 import java.util.Calendar;
+import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -1844,9 +1845,35 @@ class RangeQuery
             this.values    = new String[values.length];
             for (int i=0; i < values.length; i++) {
                 Object value = values[i];
-                this.values[i] = (value instanceof String) ?
-                        (String) value : value.toString();
-               }
+                this.values[i] = formatValue(value, type);
+            }
+        }
+
+        String formatValue(Object value, String type) {
+          if ( value == null ) {
+            return "null";
+          }
+          Class<?> valClass = value.getClass();
+          if ( String.class.isAssignableFrom(valClass) ) {
+            return (String) value;
+          } else if ( type != null &&
+              ( type.endsWith("date") || type.endsWith("dateTime") || type.endsWith("time") ) &&
+              ( Date.class.isAssignableFrom(valClass) || Calendar.class.isAssignableFrom(valClass) ) )
+          {
+            if ( Date.class.isAssignableFrom(valClass) ) {
+              Calendar cal = Calendar.getInstance();
+              cal.setTime((Date) value);
+              value = cal;
+            }
+            if ( type.endsWith("date") ) {
+              return DatatypeConverter.printDate((Calendar) value);
+            } else if ( type.endsWith("dateTime") ) {
+              return DatatypeConverter.printDateTime((Calendar) value);
+            } else if ( type.endsWith("time") ) {
+              return DatatypeConverter.printTime((Calendar) value);
+            }
+          }
+          return value.toString();
         }
         @Override
         public void innerSerialize(XMLStreamWriter serializer) throws Exception {

src/test/java/com/marklogic/client/test/PojoFacadeTest.java

@@ -20,8 +20,10 @@
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertTrue;
 
+import java.text.SimpleDateFormat;
 import java.util.Arrays;
 import java.util.Calendar;
+import java.util.Date;
 import java.util.GregorianCalendar;
 import java.util.TimeZone;
 
@@ -566,39 +568,75 @@ public void testE_IndexNumberAsString() throws Exception {
         }
     }
 
-    public static class TimeTest {     
-        @Id public String id;
-        public Calendar timeTest;
-
-        public TimeTest() {}
-        public TimeTest(String id, Calendar timeTest) {
-            this.id = id;
-            this.timeTest = timeTest;
-        }
-    }
-
     @Test
     public void testF_DateTime() {
         PojoRepository<TimeTest, String> times = Common.client.newPojoRepository(TimeTest.class, String.class);
 
-        GregorianCalendar septFirst = new GregorianCalendar(TimeZone.getTimeZone("CET"));
-        septFirst.set(2014, Calendar.SEPTEMBER, 1, 12, 0, 0);
+        GregorianCalendar septFirstUTC = new GregorianCalendar(TimeZone.getTimeZone("UTC"));
+        septFirstUTC.set(2014, Calendar.SEPTEMBER, 1, 12, 0, 0);
 
-        TimeTest timeTest1 = new TimeTest("1", septFirst);
+        TimeTest timeTest1 = new TimeTest("1", septFirstUTC);
         times.write(timeTest1);
 
         TimeTest timeTest1FromDb = times.read("1");
-        assertEquals("Times should be equal", timeTest1.timeTest.getTime().getTime(), 
-            timeTest1FromDb.timeTest.getTime().getTime());
+        assertEquals("Calendar objs should be equal", timeTest1.calendarTest,
+            timeTest1FromDb.calendarTest);
+        assertEquals("Date objs should be equal", timeTest1.dateTest,
+            timeTest1FromDb.dateTest);
+        assertEquals("Epoch time should be equal", timeTest1.dateTest.getTime(),
+            timeTest1FromDb.dateTest.getTime());
 
-        GregorianCalendar septFirstGMT = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
-        septFirstGMT.set(2014, Calendar.SEPTEMBER, 1, 12, 0, 0);
+        GregorianCalendar septThirdCET = new GregorianCalendar(TimeZone.getTimeZone("CET"));
+        septThirdCET.set(2014, Calendar.SEPTEMBER, 3, 12, 0, 0);
 
-        TimeTest timeTest2 = new TimeTest("2", septFirstGMT);
+        TimeTest timeTest2 = new TimeTest("2", septThirdCET);
         times.write(timeTest2);
 
         TimeTest timeTest2FromDb = times.read("2");
-        assertEquals("Times should be equal", timeTest2.timeTest, timeTest2FromDb.timeTest);
+        /* Jackson 2.8.3 converts all Date/Calendar to UTC, so we can't get the object in the correct timezone
+        assertEquals("Calendar objs should be equal", timeTest2.calendarTest,
+            timeTest2FromDb.calendarTestCet);
+        */
+        assertEquals("Calendar objs timestamps should be equal", timeTest2.calendarTest.getTime().getTime(),
+            timeTest2FromDb.calendarTestCet.getTime().getTime());
+        assertEquals("Date objs should be equal", timeTest2.dateTest,
+            timeTest2FromDb.dateTest);
+        assertEquals("Epoch time should be equal", timeTest2.calendarTest.getTime().getTime(),
+            timeTest2FromDb.calendarTest.getTime().getTime());
+
+        // let's try to test serializing back to CET time zone
+        /* nevermind, it turns out Jackson 2.8.3 doesn't yet support this--it converts all dates to UTC
+
+        // start with the ISO 8601 format compatible with xs:dateTime and thus MarkLogic
+        SimpleDateFormat cetDateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSXXX");
+        cetDateFormat.setTimeZone(TimeZone.getTimeZone("CET"));
+        // modify the objectMapper for this PojoRepository instance
+        ((PojoRepositoryImpl) times).getObjectMapper().setDateFormat(cetDateFormat);
+        // re-read the object with the modified objectMapper
+        timeTest2FromDb = times.read("2");
+        // now validate that the object has everything including the time zone equal
+        assertEquals("Calendar objs should be equal", timeTest2.calendarTest,
+            timeTest2FromDb.calendarTest);
+        */
+
+        // let's test a range query that should only match record "2"
+        GregorianCalendar septSecondUTC = new GregorianCalendar(TimeZone.getTimeZone("UTC"));
+        septSecondUTC.set(2014, Calendar.SEPTEMBER, 2, 12, 0, 0);
+
+        PojoQueryBuilder<TimeTest> qb = times.getQueryBuilder();
+        for ( String jsonProperty : new String[] {"calendarTest", "calendarTestCet", "dateTest"} ) {
+          PojoQueryDefinition query = qb.range(jsonProperty, Operator.GT, septSecondUTC);
+          try ( PojoPage<TimeTest> page = times.search(query, 1) ) {
+            int numRead = 0;
+            for ( TimeTest time : page ) {
+              numRead++;
+              assertEquals("Should find the right TimeTest id", "2", time.id);
+            }
+            assertEquals("Failed to find number of records expected", 1, numRead);
+            assertEquals("PojoPage failed to report number of records expected", numRead, page.size());
+          }
+        }
+
     }
 
     /* TODO: uncomment when we have a fix for https://github.com/marklogic/java-client-api/issues/383

src/test/java/com/marklogic/client/test/TimeTest.java

@@ -0,0 +1,32 @@
+package com.marklogic.client.test;
+
+import java.util.Calendar;
+import java.util.Date;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+
+import com.marklogic.client.pojo.annotation.Id;
+
+public class TimeTest {
+    @Id public String id;
+
+    @JsonTypeInfo(use=JsonTypeInfo.Id.NONE, include=JsonTypeInfo.As.EXTERNAL_PROPERTY)
+    public Calendar calendarTest;
+
+    /* The timezone below works for serializing but not for deserializing */
+    @JsonFormat(shape=JsonFormat.Shape.STRING, pattern="yyyy-MM-dd'T'HH:mm:ss.SSSXXX", timezone="CET")
+    @JsonTypeInfo(use=JsonTypeInfo.Id.NONE, include=JsonTypeInfo.As.EXTERNAL_PROPERTY)
+    public Calendar calendarTestCet;
+
+    @JsonTypeInfo(use=JsonTypeInfo.Id.NONE, include=JsonTypeInfo.As.EXTERNAL_PROPERTY)
+    public Date dateTest;
+
+    public TimeTest() {}
+    public TimeTest(String id, Calendar timestamp) {
+        this.id = id;
+        this.calendarTest = timestamp;
+        this.calendarTestCet = timestamp;
+        this.dateTest = timestamp.getTime();
+    }
+}

src/test/resources/bootstrap.xqy

@@ -402,7 +402,10 @@ declare function bootstrap:create-path-range-indexes(
         let $new-idx  := (
             "long", "com.marklogic.client.test.City/population",
             "string", "com.marklogic.client.test.City/alternateNames",
-            "string", "com.marklogic.client.test.Country/continent"
+            "string", "com.marklogic.client.test.Country/continent",
+            "dateTime", "com.marklogic.client.test.TimeTest/calendarTest",
+            "dateTime", "com.marklogic.client.test.TimeTest/calendarTestCet",
+            "dateTime", "com.marklogic.client.test.TimeTest/dateTest"
             )
         for $i in 1 to (count($new-idx) idiv 2)
         let $offset    := ($i * 2) - 1