Merge remote-tracking branch 'origin/dev' into dev

local copy

Author: Sravan Kottam

pom.xml

@@ -2,11 +2,37 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>com.marklogic</groupId>
-	<artifactId>client-api-java</artifactId>
+	<artifactId>java-client-api</artifactId>
 	<packaging>jar</packaging>
-	<version>3.0-SNAPSHOT</version>
-	<name>client-api-java</name>
-	<url>http://developer.marklogic.com</url>
+	<version>3.0.1</version>
+	<name>MarkLogic Java Client API</name>
+	<description>The official MarkLogic Java client API.</description>
+	<url>https://github.com/marklogic/java-client-api</url>
+	<licenses>
+		<license>
+			<name>The Apache License, Version 2.0</name>
+			<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+		</license>
+	</licenses>
+	<developers>
+		<developer>
+			<name>MarkLogic</name>
+			<email>java-sig@marklogic.com</email>
+			<organization>MarkLogic</organization>
+			<organizationUrl>https://www.marklogic.com</organizationUrl>
+		</developer>
+		<developer>
+			<name>MarkLogic Github Contributors</name>
+			<email>general@developer.marklogic.com</email>
+			<organization>Github Contributors</organization>
+			<organizationUrl>https://github.com/marklogic/java-client-api/graphs/contributors</organizationUrl>
+		</developer>
+	</developers>
+	<scm>
+			<connection>scm:git:git@github.com:marklogic/java-client-api.git</connection>
+			<developerConnection>scm:git:git@github.com:marklogic/java-client-api.git</developerConnection>
+		<url>git@github.com:marklogic/java-client-api.git</url>
+	</scm>
 	<properties>
 		<javadoc-title>${project.name} ${project.version} ${maven.build.timestamp}</javadoc-title>
 		<maven.build.timestamp.format>yyyy-MM-dd</maven.build.timestamp.format>

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

@@ -75,6 +75,11 @@
  * 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.
+ *
+ * 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.
  */
 public interface PojoRepository<T, ID extends Serializable> {
     /** Write this instance to the database.  Uses the field marked with {@literal @}Id 
@@ -249,7 +254,7 @@ public T read(ID id, Transaction transaction)
     public PojoPage<T> read(ID[] ids)
         throws ForbiddenUserException, FailedRequestException;
     /** Within an open transaction,
-     * read one page of persisted pojos and unmarshall their data into new pojo instances.
+     * read multiple persisted pojos and unmarshall their data into new pojo instances.
      * If at least one instance is found but others are not, ignores the instances not found.
      * While this returns a PojoPage, the PageSize will match the number of instances found,
      * and will ignore getPageLength().  To paginate, send a smaller set of ids at a time.
@@ -258,9 +263,9 @@ public PojoPage<T> read(ID[] ids)
      * @param transaction the transaction in which this read is participating
      *      (will open a read lock on each document matched that is released when the
      *      transaction is committed or rolled back)
-     * @return a page of instances of the correct type populated with the persisted data.
-     *      Since this call may match a large set, only one page of {@link #getPageLength()}
-     *      is returned just like calls to {@link #search(PojoQueryDefinition, long) search}
+     * @return a set of instances of the correct type populated with the persisted data.
+     *      Since this call produces a finite set, only one page is returned and therefore
+     *      PojoPage pagination methods will not be helpful as they would be from calls to search.
      */
     public PojoPage<T> read(ID[] ids, Transaction transaction)
         throws ForbiddenUserException, FailedRequestException;

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

@@ -41,7 +41,8 @@
 import com.marklogic.client.query.StructuredQueryDefinition;
 
 public class BitemporalTest {
-	// bootstrap.xqy sets up the "temporal-collection" and required underlying axes
+	// src/test/resources/bootstrap.xqy is run by src/test/resources/boot-test.sh
+	// and sets up the "temporal-collection" and required underlying axes
 	// system-axis and valid-axis which have required underlying range indexes
 	// system-start, system-end, valid-start, and valid-end
 	static String temporalCollection = "temporal-collection";
@@ -66,29 +67,29 @@ public void test1() throws Exception {
 				uniqueTerm + " version1" +
 				"<system-start></system-start>" +
 				"<system-end></system-end>" +
-				"<valid-start>2014-08-19T00:00:00</valid-start>" +
-				"<valid-end>2014-08-19T00:00:01</valid-end>" +
+				"<valid-start>2014-08-19T00:00:00Z</valid-start>" +
+				"<valid-end>2014-08-19T00:00:01Z</valid-end>" +
     		"</test>";
 		String version2 = "<test>" +
 				uniqueTerm + " version2" +
 				"<system-start></system-start>" +
 				"<system-end></system-end>" +
-				"<valid-start>2014-08-19T00:00:02</valid-start>" +
-				"<valid-end>2014-08-19T00:00:03</valid-end>" +
+				"<valid-start>2014-08-19T00:00:02Z</valid-start>" +
+				"<valid-end>2014-08-19T00:00:03Z</valid-end>" +
     		"</test>";
 		String version3 = "<test>" +
 				uniqueTerm + " version3" +
 				"<system-start></system-start>" +
 				"<system-end></system-end>" +
-				"<valid-start>2014-08-19T00:00:03</valid-start>" +
-				"<valid-end>2014-08-19T00:00:04</valid-end>" +
+				"<valid-start>2014-08-19T00:00:03Z</valid-start>" +
+				"<valid-end>2014-08-19T00:00:04Z</valid-end>" +
     		"</test>";
 		String version4 = "<test>" +
 				uniqueTerm + " version4" +
 				"<system-start></system-start>" +
 				"<system-end></system-end>" +
-				"<valid-start>2014-08-19T00:00:05</valid-start>" +
-				"<valid-end>2014-08-19T00:00:06</valid-end>" +
+				"<valid-start>2014-08-19T00:00:05Z</valid-start>" +
+				"<valid-end>2014-08-19T00:00:06Z</valid-end>" +
     		"</test>";
 		XMLDocumentManager docMgr = Common.client.newXMLDocumentManager();
 		StringHandle handle1 = new StringHandle(version1).withFormat(Format.XML);
@@ -112,24 +113,26 @@ public void test1() throws Exception {
 		DocumentPage termQueryResults = docMgr.search(termQuery, start);
 		assertEquals("Wrong number of results", 4, termQueryResults.size());
 
-		// sleep for 2 seconds
+		// temporal-collection is configured to automatically advance lsqt every 1 second
+		// so we'll sleep for 2 seconds to make sure lsqt has advanced beyond the lsqt
+		// when we inserted our documents
 		Thread.sleep(2000);
 		StructuredQueryDefinition currentQuery = sqb.temporalLsqtQuery(temporalCollection, null, 1);
 		StructuredQueryDefinition currentDocQuery = sqb.and(termQuery, currentQuery);
 		DocumentPage currentDocQueryResults = docMgr.search(currentDocQuery, start);
 		assertEquals("Wrong number of results", 4, currentDocQueryResults.size());
 
 		StructuredQueryBuilder.Axis validAxis = sqb.axis("valid-axis");
-		Calendar start1 = DatatypeConverter.parseDateTime("2014-08-19T00:00:00");
-		Calendar end1 = DatatypeConverter.parseDateTime("2014-08-19T00:00:04");
+		Calendar start1 = DatatypeConverter.parseDateTime("2014-08-19T00:00:00Z");
+		Calendar end1   = DatatypeConverter.parseDateTime("2014-08-19T00:00:04Z");
 		StructuredQueryBuilder.Period period1 = sqb.period(start1, end1);
 		StructuredQueryDefinition periodQuery1 = sqb.and(sqb.term(uniqueTerm),
 			sqb.temporalPeriodRange(validAxis, TemporalOperator.ALN_CONTAINED_BY, period1));
 		DocumentPage periodQuery1Results = docMgr.search(periodQuery1, start);
 		assertEquals("Wrong number of results", 1, periodQuery1Results.size());
 
-		Calendar start2 = DatatypeConverter.parseDateTime("2014-08-19T00:00:04");
-		Calendar end2 = DatatypeConverter.parseDateTime("2014-08-19T00:00:07");
+		Calendar start2 = DatatypeConverter.parseDateTime("2014-08-19T00:00:04Z");
+		Calendar end2   = DatatypeConverter.parseDateTime("2014-08-19T00:00:07Z");
 		StructuredQueryBuilder.Period period2 = sqb.period(start2, end2);
 		StructuredQueryDefinition periodQuery2 = sqb.and(sqb.term(uniqueTerm),
 			sqb.temporalPeriodRange(validAxis, TemporalOperator.ALN_CONTAINED_BY, period2));