Merge branch 'release-3.0.0-EA2'

README.md

@@ -27,8 +27,8 @@ mvn test
 The following resources introduce and document the Java API:
 
 * [The Java API in Five Minutes](http://developer.marklogic.com/try/java/index)
-* [JavaDoc](http://docs.marklogic.com/guide/java)
-* [User Guide](http://docs.marklogic.com/javadoc/client/index.html)
+* [Java Application Developer's Guide](http://docs.marklogic.com/guide/java)
+* [JavaDoc](http://docs.marklogic.com/javadoc/client/index.html)
 
 ### Installing
 

pom.xml

@@ -4,14 +4,22 @@
 	<groupId>com.marklogic</groupId>
 	<artifactId>client-api-java</artifactId>
 	<packaging>jar</packaging>
-	<version>3.0-SNAPSHOT</version>
+	<version>3.0.0-EA2</version>
 	<name>client-api-java</name>
 	<url>http://developer.marklogic.com</url>
 	<properties>
 		<javadoc-title>${project.name} 2.0 ${maven.build.timestamp}</javadoc-title>
 		<maven.build.timestamp.format>yyyy-MM-dd</maven.build.timestamp.format>
 		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <github.global.server>github</github.global.server>
 	</properties>
+    <distributionManagement>
+        <repository>
+            <id>internal.repo</id>
+            <name>Temporary Staging Repository</name>
+            <url>file://${project.build.directory}/mvn-repo</url>
+        </repository>
+    </distributionManagement>
 	<build>
 		<plugins>
 			<plugin>
@@ -120,6 +128,37 @@
 					</execution>
 				</executions>
 			</plugin>
+            <plugin>
+                <artifactId>maven-deploy-plugin</artifactId>
+                <version>2.8.1</version>
+                <configuration>
+                    <altDeploymentRepository>internal.repo::default::file://${project.build.directory}/mvn-repo</altDeploymentRepository>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>com.github.github</groupId>
+                <artifactId>site-maven-plugin</artifactId>
+                <version>0.9</version>
+                <configuration>
+                    <message>Maven artifacts for ${project.version}</message>
+                    <merge>true</merge>
+                    <noJekyll>true</noJekyll>
+                    <outputDirectory>${project.build.directory}/mvn-repo</outputDirectory>
+                    <branch>refs/heads/mvn-repo</branch>
+                    <includes><include>**/*</include></includes>
+                    <repositoryName>java-client-api</repositoryName>
+                    <repositoryOwner>marklogic</repositoryOwner>
+                </configuration>
+                <executions>
+                    <!-- run site-maven-plugin's 'site' target as part of the build's normal 'deploy' phase -->
+                    <execution>
+                        <goals>
+                            <goal>site</goal>
+                        </goals>
+                        <phase>deploy</phase>
+                    </execution>
+                </executions>
+        </plugin>
 		</plugins>
 	</build>
 	<dependencies>
@@ -174,10 +213,20 @@
 			<artifactId>slf4j-api</artifactId>
 			<version>1.7.4</version>
 		</dependency>
+		<dependency>
+			<groupId>com.fasterxml.jackson.core</groupId>
+			<artifactId>jackson-core</artifactId>
+			<version>2.4.1</version>
+		</dependency>
+		<dependency>
+			<groupId>com.fasterxml.jackson.core</groupId>
+			<artifactId>jackson-annotations</artifactId>
+			<version>2.4.1</version>
+		</dependency>
 		<dependency>
 			<groupId>com.fasterxml.jackson.core</groupId>
 			<artifactId>jackson-databind</artifactId>
-			<version>2.2.1</version>
+			<version>2.4.1</version>
 		</dependency>
 		<!-- test dependencies -->
 		<dependency>
@@ -229,5 +278,29 @@
 			<version>2.3</version>
 			<scope>provided</scope>
 		</dependency>
+		<dependency>
+			<groupId>org.geonames</groupId>
+			<artifactId>geonames</artifactId>
+			<version>1.0</version>
+			<scope>provided</scope>
+		</dependency>
+		<dependency>
+			<groupId>com.fasterxml.jackson.dataformat</groupId>
+			<artifactId>jackson-dataformat-xml</artifactId>
+			<version>2.4.1</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>com.fasterxml.jackson.dataformat</groupId>
+			<artifactId>jackson-dataformat-csv</artifactId>
+			<version>2.4.1</version>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>com.google.guava</groupId>
+			<artifactId>guava</artifactId>
+			<version>16.0.1</version>
+			<scope>test</scope>
+		</dependency>
 	</dependencies>
 </project>

src/main/java/com/marklogic/client/DatabaseClient.java

@@ -16,6 +16,7 @@
 package com.marklogic.client;
 
 import java.io.OutputStream;
+import java.io.Serializable;
 
 import com.marklogic.client.admin.ServerConfigurationManager;
 import com.marklogic.client.document.BinaryDocumentManager;
@@ -28,6 +29,7 @@
 import com.marklogic.client.query.QueryManager;
 import com.marklogic.client.alerting.RuleManager;
 import com.marklogic.client.util.RequestLogger;
+import com.marklogic.client.pojo.PojoRepository;
 
 /**
  * A Database Client instantiates document and query managers and other objects
@@ -110,6 +112,19 @@ public interface DatabaseClient {
      */
     public ServerConfigurationManager newServerConfigManager();
 
+    /**
+     * Creates a PojoRepository specific to the specified class and its id type. 
+     * The PojoRepository provides a facade for persisting, retrieving, and
+     * querying data contained in Java objects.  Annotations are required to
+     * identify the id field and any fields for which you wish to create indexes.
+     *
+     * @param clazz the class type for this PojoRepository to handle
+     * @param idClass the class type of the id field for this clazz, must obviously 
+     *          be Serializable or we'll struggle to marshall it
+     * @return the initialized PojoRepository
+     **/
+    public <T, ID extends Serializable> PojoRepository<T, ID> newPojoRepository(Class<T> clazz, Class<ID> idClass);
+
     /**
      * Initializes a manager for a extension resource.
      * 

src/main/java/com/marklogic/client/Page.java

@@ -17,17 +17,66 @@
 
 import java.util.Iterator;
 
+/** A generic interface for pagination through large sets of items of type <T>. */
 public interface Page<T> extends Iterable<T> {
+    /** An iterator over the items in this page. */
     public Iterator<T> iterator();
+
+    /** The start position of this page within all possible items.  For result sets
+     * this is the position of the first result within the result set.
+     * @return the start position
+     */
     public long getStart();
+
+    /** The page size which is the maximum number of items allowed in one page.
+     * @return the page size */
     public long getPageSize();
+
+    /** The total count (potentially an estimate) of all possible items in the set.
+     *  For result sets this is the number of items within the result set.
+     *  For search result sets this is the estimated number of matching items.
+     * @return the total count of possible items */
     public long getTotalSize();
+
+    /** The count of items in this page, which is always less than getPageSize().  
+     * If ({@link #getTotalSize()} - {@link #getStart()}) &gt; {@link #getPageSize()}
+     * then size() == getPageSize().
+     * @return the count of items in this page
+     */
     public long size();
+
+
+    /** The number of pages covering all possible items. 
+     * @return the number of pages.  Literally, 
+     * <pre>{@code (long) Math.ceil((double) getTotalSize() / (double) getPageSize()); }</pre>
+     */
     public long getTotalPages();
+
+    /** Whether there are any items in this page.  
+     * @return true if {@code size() > 0; }
+     */
     public boolean hasContent();
+
+    /** Whether there are any items in the next page.  
+     * @return true if {@code getPageNumber() < getTotalPages(); }
+     */
     public boolean hasNextPage();
+
+    /** Whether there is a previous page.  
+     * @return true if {@code getPageNumber() > 0 }
+     */
     public boolean hasPreviousPage();
+
+    /** The page number within the count of all possible pages.  
+     * @return {@code (long) Math.floor((double) start / (double) getPageSize()) + 1; }
+     */
     public long getPageNumber();
+
+    /** @return true if {@code getPageNumber() == 1 }
+     */
     public boolean isFirstPage();
+
+    /** @return true if {@code getPageNumber() == getTotalPages() }
+     */
     public boolean isLastPage();
 }

src/main/java/com/marklogic/client/admin/config/QueryOptions.java

@@ -49,15 +49,17 @@
  * {@link com.marklogic.client.io.marker.StructureReadHandle read handle}
  * implementation instead of this class to write or read
  * query options.  For instance:
- * <pre>String opts = new StringBuilder()
- *     .append("&lt;options xmlns=\"http://marklogic.com/appservices/search\">")
- *     .append(    "&lt;debug>true&lt;/debug>")
- *     .append("&lt;/options>")
- *     .toString();
- *optsMgr.writeOptions("debug", new StringHandle(opts));</pre>
+ * <pre>{@code
+ *  String opts = new StringBuilder()
+ *      .append("<options xmlns=\"http://marklogic.com/appservices/search\">")
+ *      .append(    "<debug>true</debug>")
+ *      .append("</options>")
+ *      .toString();
+ *  optsMgr.writeOptions("debug", new StringHandle(opts)); }</pre>
  * or
- * <pre>String opts = "{\"options\":{\"debug\":true}}";
- *optsMgr.writeOptions("debug", new StringHandle(opts).withFormat(Format.JSON));</pre>
+ * <pre>{@code
+ *  String opts = "{\"options\":{\"debug\":true}}";
+ *  optsMgr.writeOptions("debug", new StringHandle(opts).withFormat(Format.JSON)); }</pre>
  */
 @Deprecated
 @XmlAccessorType(XmlAccessType.FIELD)

src/main/java/com/marklogic/client/admin/config/QueryOptionsBuilder.java

@@ -94,15 +94,17 @@
  * {@link com.marklogic.client.io.marker.StructureReadHandle read handle}
  * implementation instead of this class to write or read
  * query options.  For instance:
- * <pre>String opts = new StringBuilder()
- *     .append("&lt;options xmlns=\"http://marklogic.com/appservices/search\">")
- *     .append(    "&lt;debug>true&lt;/debug>")
- *     .append("&lt;/options>")
- *     .toString();
- *optsMgr.writeOptions("debug", new StringHandle(opts));</pre>
+ * <pre>{@code
+ *  String opts = new StringBuilder()
+ *       .append("<options xmlns=\"http://marklogic.com/appservices/search\">")
+ *       .append(    "<debug>true</debug>")
+ *       .append("</options>")
+ *       .toString();
+ *  optsMgr.writeOptions("debug", new StringHandle(opts)); }</pre>
  * or
- * <pre>String opts = "{\"options\":{\"debug\":true}}";
- *optsMgr.writeOptions("debug", new StringHandle(opts).withFormat(Format.JSON));</pre>
+ * <pre>{@code
+ *  String opts = "{\"options\":{\"debug\":true}}";
+ *  optsMgr.writeOptions("debug", new StringHandle(opts).withFormat(Format.JSON)); }</pre>
  */
 @Deprecated
 public class QueryOptionsBuilder {

src/main/java/com/marklogic/client/document/DocumentManager.java

@@ -30,6 +30,7 @@
 import com.marklogic.client.io.marker.DocumentPatchHandle;
 import com.marklogic.client.io.marker.SearchReadHandle;
 import com.marklogic.client.query.QueryDefinition;
+import com.marklogic.client.query.QueryManager.QueryView;
 
 /**
  * A Document Manager provides database operations on a document.
@@ -367,14 +368,58 @@ public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle
     public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle metadataHandle, T contentHandle, ServerTransform transform, Transaction transaction)
 		throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
 
+    /**
+     * Reads from the database a list of documents matching the provided uris.  Allows
+     * iteration across matching documents and metadata (only if setMetadataCategories 
+     * has been called to request metadata).  To find out how many of your uris matched,
+     * call the {@link DocumentPage#size() DocumentPage.size()} method.
+     *
+     * @param uris the database uris identifying documents to retrieve
+     * @return the DocumentPage of matching documents and metadata
+     */
     public DocumentPage read(String... uris);
 
+    /**
+     * Reads from the database a list of documents matching the provided uris.  Allows
+     * iteration across matching documents and metadata (only if setMetadataCategories 
+     * has been called to request metadata).  To find out how many of your uris matched,
+     * call the {@link DocumentPage#size() DocumentPage.size()} method.
+     *
+     * @param transform the transform to be run on the server on each document (must already be installed)
+     * @param uris the database uris identifying documents to retrieve
+     * @return the DocumentPage of matching documents and metadata
+     */
     public DocumentPage read(ServerTransform transform, String... uris);
 
+    /**
+     * Reads from the database a list of documents matching the provided uris.  Allows
+     * iteration across matching documents and metadata (only if setMetadataCategories 
+     * has been called to request metadata).  To find out how many of your uris matched,
+     * call the {@link DocumentPage#size() DocumentPage.size()} method.
+     *
+     * @param transaction the transaction in which this read is participating
+     * @param uris the database uris identifying documents to retrieve
+     * @return the DocumentPage of matching documents and metadata
+     */
     public DocumentPage read(Transaction transaction, String... uris);
 
+    /**
+     * Reads from the database a list of documents matching the provided uris.  Allows
+     * iteration across matching documents and metadata (only if setMetadataCategories 
+     * has been called to request metadata).  To find out how many of your uris matched,
+     * call the {@link DocumentPage#size() DocumentPage.size()} method.
+     *
+     * @param transform the transform to be run on the server on each document (must already be installed)
+     * @param transaction the transaction in which this read is participating
+     * @param uris the database uris identifying documents to retrieve
+     * @return the DocumentPage of matching documents and metadata
+     */
     public DocumentPage read(ServerTransform transform, Transaction transaction, String... uris);
 
+    public DocumentPage readMetadata(String... uris);
+
+    public DocumentPage readMetadata(Transaction transaction, String... uris);
+
     public DocumentPage search(QueryDefinition querydef, long start);
 
     public DocumentPage search(QueryDefinition querydef, long start, Transaction transaction);
@@ -387,6 +432,14 @@ public <T extends R> T read(DocumentDescriptor desc, DocumentMetadataReadHandle
 
     public void setPageLength(long length);
 
+    public Format getResponseFormat();
+
+    public void setResponseFormat(Format format);
+
+    public QueryView getSearchView();
+
+    public void setSearchView(QueryView view);
+
     public DocumentWriteSet newWriteSet();
 
     public void write(DocumentWriteSet writeSet);

src/main/java/com/marklogic/client/document/DocumentPatchBuilder.java

@@ -57,6 +57,36 @@ public String toString() {
 		}
 	}
 
+
+	/**
+	 * MarkLogic's REST API patch operations support two path languages for JSON,
+	 * XPATH and JSONPATH.  Default for MarkLogic 8 is XPATH,
+	 * but you can use the backwards-compatible JSONPATH too.
+	 */
+	public enum PathLanguage {
+
+		/**
+		 * Indicates that the given patch uses the XPATH language.
+		 */
+		XPATH, 
+
+		/**
+		 * Indicates that the given patch uses the JSONPATH language.
+		 */
+		JSONPATH;
+
+		@Override
+		public String toString() {
+			return super.toString().toLowerCase();
+		};
+
+	}
+
+	/**
+	 * Specifies the language for this patch to use
+	 */
+	public DocumentPatchBuilder pathLanguage(PathLanguage pathLang);
+
 	/**
 	 * Specifies an operation to delete an existing JSON or XML fragment.
 	 * @param selectPath	the location of the JSON or XML fragment