fix #845 - remove markdown from javadocs and replace with html

Author: sammefford

src/main/java/com/marklogic/client/datamovement/ApplyTransformListener.java

@@ -31,65 +31,72 @@
 import java.util.stream.Collectors;
 
 /**
- * Modifies documents in-place in the database by applying a {@link
+ * <p>Modifies documents in-place in the database by applying a {@link
  * com.marklogic.client.document.ServerTransform server-side transform}.
  * If the transform modifies documents to no longer match the query,
- * ApplyTransformListener should only be used when:
+ * ApplyTransformListener should only be used when:</p>
  *
- * 1. [merge timestamp][] is enabled and
- * {@link QueryBatcher#withConsistentSnapshot} is called, or
- * 2. {@link DataMovementManager#newQueryBatcher(Iterator)
- * newQueryBatcher(Iterator&lt;String&gt;)} is used to traverse a static data set
+ * <ol>
+ *   <li><a href="https://docs.marklogic.com/guide/app-dev/point_in_time#id_32468">merge timestamp</a>
+ *     is enabled and {@link QueryBatcher#withConsistentSnapshot} is called, or</li>
+ *   <li>{@link DataMovementManager#newQueryBatcher(Iterator)
+ *     newQueryBatcher(Iterator&lt;String&gt;)} is used to traverse a static data set</li>
+ * </ol>
  *
- * [merge timestamp]: https://docs.marklogic.com/guide/app-dev/point_in_time#id_32468
+ * <br>For example, given the REST transform myTransform.sjs:
  *
- * For example, given the REST transform myTransform.sjs:
- *
- *     function transform_function(context, params, content) {
- *       var document = content.toObject();
- *       document.someProperty = params.newValue;
- *       return document;
- *     };
- *     exports.transform = transform_function;
+ * <pre>{@code
+ *    function transform_function(context, params, content) {
+ *      var document = content.toObject();
+ *      document.someProperty = params.newValue;
+ *      return document;
+ *    };
+ *    exports.transform = transform_function;
+ *}</pre>
  *
  * installed in the server like so (using the MarkLogic Java Client API):
  *
- *     restAdminClient.newServerConfigManager().newTransformExtensionsManager().writeJavascriptTransform(
- *       "myTransform", new FileHandle(new File("myTransform.sjs")));
+ * <pre>{@code
+ *    restAdminClient.newServerConfigManager().newTransformExtensionsManager().writeJavascriptTransform(
+ *      "myTransform", new FileHandle(new File("myTransform.sjs")));
+ *}</pre>
  *
  * you can run the transform on documents matching a query like so:
  *
- *     ServerTransform transform = new ServerTransform(transformName2)
- *         .addParameter("newValue", "some new value");
- *     ApplyTransformListener listener = new ApplyTransformListener()
- *       .withTransform(transform)
- *       .withApplyResult(ApplyResult.REPLACE);
- *     QueryBatcher batcher = moveMgr.newQueryBatcher(query)
- *         .onUrisReady(listener);
- *     JobTicket ticket = moveMgr.startJob( batcher );
- *     batcher.awaitCompletion();
- *     moveMgr.stopJob(ticket);
- *
- * As with all the provided listeners, this listener will not meet the needs of
- * all applications but the [source code][] for it should serve as helpful sample
- * code so you can write your own custom listeners.
+ * <pre>{@code
+ *    ServerTransform transform = new ServerTransform(transformName2)
+ *      .addParameter("newValue", "some new value");
+ *    ApplyTransformListener listener = new ApplyTransformListener()
+ *      .withTransform(transform)
+ *      .withApplyResult(ApplyResult.REPLACE);
+ *    QueryBatcher batcher = moveMgr.newQueryBatcher(query)
+ *      .onUrisReady(listener);
+ *    JobTicket ticket = moveMgr.startJob( batcher );
+ *    batcher.awaitCompletion();
+ *    moveMgr.stopJob(ticket);
+ *}</pre>
  *
- * [source code]: https://github.com/marklogic/java-client-api/blob/develop/src/main/java/com/marklogic/client/datamovement/ApplyTransformListener.java
+ * <p>As with all the provided listeners, this listener will not meet the needs
+ * of all applications but the
+ * <a target="_blank" href="https://github.com/marklogic/java-client-api/blob/develop/src/main/java/com/marklogic/client/datamovement/ApplyTransformListener.java">source code</a>
+ * for it should serve as helpful sample code so you can write your own custom
+ * listeners.</p>
  *
- * In this listener, we initialize only the HostAvailabilityListener's
+ * <p>In this listener, we initialize only the HostAvailabilityListener's
  * RetryListener and not NoResponseListener's RetryListener because if we get
  * empty responses when we try to apply a transform to the batch of URIs
  * retrieved from the server, we are not sure what happened in the server - if
  * the transform has been applied or it has not been applied. Retrying in those
  * scenarios would apply the transform twice if the transform has been already
- * applied and this is not desirable.
+ * applied and this is not desirable.</p>
  *
- * In order to handle such scenarios where we get an empty response, it is
+ * <p>In order to handle such scenarios where we get an empty response, it is
  * recommended to add a BatchFailureListener which would take care of apply
  * transform failures and retry only for those URIs for which the apply
  * transform has failed. If the transform is idempotent, we can just initialize 
- * the RetryListener of the NoResponseListener by calling NoResponseListener.initializeRetryListener(this)
- * and add it to the BatchFailureListeners similar to what we have in the other listeners.
+ * the RetryListener of the NoResponseListener by calling
+ * NoResponseListener.initializeRetryListener(this) and add it to the
+ * BatchFailureListeners similar to what we have in the other listeners.</p>
  */
 public class ApplyTransformListener implements QueryBatchListener {
   private static Logger logger = LoggerFactory.getLogger(ApplyTransformListener.class);
@@ -105,6 +112,11 @@ public ApplyTransformListener() {
       "if you see this once/batch, fix your job configuration");
   }
 
+  /**
+   * This implementation of initializeListener adds this instance of
+   * ApplyTransformListener to the two RetryListener's in this QueryBatcher so
+   * they will retry any batches that fail during the apply-transform request.
+   */
   @Override
   public void initializeListener(QueryBatcher queryBatcher) {
     HostAvailabilityListener hostAvailabilityListener = HostAvailabilityListener.getInstance(queryBatcher);

src/main/java/com/marklogic/client/datamovement/BatchListener.java

@@ -23,25 +23,27 @@
  */
 public interface BatchListener<T extends Batch<?>> {
   /**
-   * The method called by QueryBatcher or WriteBatcher to run your
-   * custom code on this batch.  You usually implement this as a lambda expression.
+   * <p>The method called by QueryBatcher or WriteBatcher to run your
+   * custom code on this batch.  You usually implement this as a lambda expression.</p>
    *
    * For example, see the lambda expression passed to onUrisReady:
    *
+   * <pre>{@code
    *     QueryBatcher qhb = dataMovementManager.newQueryBatcher(query)
    *         .withBatchSize(1000)
    *         .withThreadCount(20)
-   *         .onUrisReady(batch -&gt; {
+   *         .onUrisReady(batch -> {
    *             for ( String uri : batch.getItems() ) {
    *                 if ( uri.endsWith(".txt") ) {
    *                     batch.getClient().newDocumentManager().delete(uri);
    *                 }
    *             }
    *         })
-   *         .onQueryFailure(queryBatchException -&gt; queryBatchException.printStackTrace());
+   *         .onQueryFailure(queryBatchException -> queryBatchException.printStackTrace());
    *     JobTicket ticket = dataMovementManager.startJob(qhb);
    *     qhb.awaitCompletion();
    *     dataMovementManager.stopJob(ticket);
+   *}</pre>
    *
    * @param batch the batch of uris and some metadata about the current status of the job
    */

src/main/java/com/marklogic/client/datamovement/Batcher.java

@@ -45,11 +45,11 @@ public interface Batcher {
   String getJobId();
 
   /**
-   * The size of each batch (usually 50-500). With some experimentation with
+   * <p>The size of each batch (usually 50-500). With some experimentation with
    * your custom job, this value can be tuned. Tuning this value is one of the
-   * best ways to achieve optimal throughput.
+   * best ways to achieve optimal throughput.</p>
    *
-   * This method cannot be called after the job has started.
+   * <p>This method cannot be called after the job has started.</p>
    *
    * @param batchSize the batch size -- must be 1 or greater
    * @return this instance (for method chaining)
@@ -62,15 +62,15 @@ public interface Batcher {
   int getBatchSize();
 
   /**
-   * The number of threads to be used internally by this job to perform
+   * <p>The number of threads to be used internally by this job to perform
    * concurrent tasks on batches (usually &gt; 10).  With some experimentation with your custom
    * job and client environment, this value can be tuned.  Tuning this value is
    * one of the best ways to achieve optimal throughput or to throttle the
    * server resources used by this job.  Setting this to 1 does not guarantee
    * that batches will be processed sequentially because the calling thread
-   * will sometimes also process batches.
+   * will sometimes also process batches.</p>
    *
-   * This method cannot be called after the job has started.
+   * <p>This method cannot be called after the job has started.</p>
    *
    * @param threadCount the number of threads to use in this Batcher
    *

src/main/java/com/marklogic/client/datamovement/DataMovementManager.java

@@ -26,7 +26,7 @@
 import java.util.Iterator;
 
 /**
- * DataMovementManager is the starting point for getting new instances of
+ * <p>DataMovementManager is the starting point for getting new instances of
  * QueryBatcher and WriteBatcher, configured with a DatabaseClient and
  * ForestConfiguration.  On instantiation, it will immediately call
  * readForestConfig to obtain the ForestConfiguration from which it can create
@@ -36,16 +36,18 @@
  * the port in the DatabaseClient.  Call {@link #release()
  * dataMovementMangaer.release()} when you're done with your
  * DataMovementManager instance to free resources associated with those
- * host-specific DatabaseClient instances.
+ * host-specific DatabaseClient instances.</p>
  *
  * Sample Usage:
  *
+ * <pre>{@code
  *     DataMovementManager dataMovementManager = databaseClient.newDataMovementManager();
  *     WriteBatcher batcher = dataMovementManager.newWriteBatcher();
  *     dataMovementManager.startJob(batcher);
  *     . . .
  *     dataMovementManager.stopJob(batcher);
  *     dataMovementManager.release();
+ *}</pre>
  */
 public interface DataMovementManager {
   /** Calls release() on all host-specific DatabaseClient instances (but not on
@@ -159,17 +161,16 @@ public interface DataMovementManager {
   public QueryBatcher newQueryBatcher(RawCombinedQueryDefinition query);
 
   /**
-   * Create a new QueryBatcher instance configured to retrieve uris from this
+   * <p>Create a new QueryBatcher instance configured to retrieve uris from this
    * Iterator.  This form enables the uris (actually any String) to come from
    * any source, whereas the other form requires the uris to come from the
    * results of a query.  This form is helpful when deleting documents when one
-   * cannot set the server's [merge timestamp][].  For more discussion, see
-   * {@link QueryBatcher}.
+   * cannot set the server's
+   * <a href="https://docs.marklogic.com/guide/app-dev/point_in_time#id_32468">merge timestamp</a>.
+   * For more discussion, see {@link QueryBatcher}.</p>
    *
-   * The Iterator needn't be thread-safe as it is only iterated from one
-   * thread.
-   *
-   * [merge timestamp]: https://docs.marklogic.com/guide/app-dev/point_in_time#id_32468
+   * <p>The Iterator needn't be thread-safe as it is only iterated from one
+   * thread.</p>
    *
    * @param iterator the provider of uris
    *

src/main/java/com/marklogic/client/datamovement/DeleteListener.java

@@ -22,42 +22,46 @@
 import java.util.List;
 
 /**
- * Sends a Java API bulk {@link com.marklogic.client.document.DocumentManager#delete(String...) delete}
+ * <p>Sends a Java API bulk {@link com.marklogic.client.document.DocumentManager#delete(String...) delete}
  * request for all the documents from each batch.  Because it deletes
- * documents, it should only be used when:
+ * documents, it should only be used when:</p>
  *
- * 1. [merge timestamp][] is enabled and
- * {@link QueryBatcher#withConsistentSnapshot} is called, or
- * 2. {@link DataMovementManager#newQueryBatcher(Iterator)
- * newQueryBatcher(Iterator&lt;String&gt;)} is used to traverse a static data set
+ * <ol>
+ *   <li><a href="https://docs.marklogic.com/guide/app-dev/point_in_time#id_32468">merge timestamp</a>
+ *     is enabled and {@link QueryBatcher#withConsistentSnapshot} is called, or</li>
+ *   <li>{@link DataMovementManager#newQueryBatcher(Iterator)
+ *     newQueryBatcher(Iterator&lt;String&gt;)} is used to traverse a static data set</li>
+ * </ol>
  *
- * [merge timestamp]: https://docs.marklogic.com/guide/app-dev/point_in_time#id_32468
- *
- * When merge timestamp is enabled, pass a DeleteListener instance to
+ * <br>When merge timestamp is enabled, pass a DeleteListener instance to
  * QueryBatcher onUrisReady like so:
  *
+ * <pre>{@code
  *     QueryBatcher deleteBatcher = moveMgr.newQueryBatcher(query)
  *       .onUrisReady(new DeleteListener())
  *       .withConsistentSnapshot();
  *     JobTicket ticket = moveMgr.startJob(deleteBatcher);
  *     deleteBatcher.awaitCompletion();
  *     moveMgr.stopJob(ticket);
+ *}</pre>
  *
  * With Iterator&lt;String&gt;, pass a DeleteListener instance to
  * QueryBatcher onUrisReady like so:
  *
+ * <pre>{@code
  *     QueryBatcher deleteBatcher = moveMgr.newQueryBatcher(query)
  *       .onUrisReady(new DeleteListener());
  *     JobTicket ticket = moveMgr.startJob(deleteBatcher);
  *     deleteBatcher.awaitCompletion();
  *     moveMgr.stopJob(ticket);
+ *}</pre>
  *
- * As with all the provided listeners, this listener will not meet the needs of
- * all applications but the [source code][] for it should serve as helpful sample
- * code so you can write your own custom listeners.
- *
- * [source code]: https://github.com/marklogic/java-client-api/blob/develop/src/main/java/com/marklogic/client/datamovement/DeleteListener.java
- */
+ * <p>As with all the provided listeners, this listener will not meet the needs
+ * of all applications but the
+ * <a target="_blank" href="https://github.com/marklogic/java-client-api/blob/develop/src/main/java/com/marklogic/client/datamovement/DeleteListener.java">source code</a>
+ * for it should serve as helpful sample code so you can write your own custom
+ * listeners.</p>
+*/
 public class DeleteListener implements QueryBatchListener {
   private static Logger logger = LoggerFactory.getLogger(DeleteListener.class);
   private List<BatchFailureListener<Batch<String>>> failureListeners = new ArrayList<>();
@@ -68,6 +72,11 @@ public DeleteListener() {
       "if you see this once/batch, fix your job configuration");
   }
 
+  /**
+   * This implementation of initializeListener adds this instance of
+   * DeleteListener to the two RetryListener's in this QueryBatcher so they
+   * will retry any batches that fail during the delete request.
+   */
   @Override
   public void initializeListener(QueryBatcher queryBatcher) {
     HostAvailabilityListener hostAvailabilityListener = HostAvailabilityListener.getInstance(queryBatcher);

src/main/java/com/marklogic/client/datamovement/ExportListener.java

@@ -34,39 +34,41 @@
 import java.util.Set;
 
 /**
- * Reads document contents (and optionally metadata) for each batch, then sends
+ * <p>Reads document contents (and optionally metadata) for each batch, then sends
  * each document to any listeners registered with {@link #onDocumentReady
  * onDocumentReady} for further processing or writing to any target supported
  * by Java.  Supports reading partial documents via transforms.  Supports
  * exporting all documents at a consistent point-in-time using
- * withConsistentSnapshot.
+ * withConsistentSnapshot.</p>
  *
  * For example:
  *
+ * <pre>{@code
  *     QueryBatcher exportBatcher = moveMgr.newQueryBatcher(query)
  *         .withConsistentSnapshot()
  *         .onUrisReady(
  *           new ExportListener()
- *               .withConsistentSnapshot()
- *               .onDocumentReady(doc -&gt; {
- *                 logger.debug("Contents=[{}]", doc.getContentAs(String.class));
- *               })
+ *             .withConsistentSnapshot()
+ *             .onDocumentReady(doc -> {
+ *               logger.debug("Contents=[{}]", doc.getContentAs(String.class));
+ *             })
  *         )
- *         .onQueryFailure(exception -&gt; exception.printStackTrace());
+ *         .onQueryFailure(exception -> exception.printStackTrace());
  *
  *     JobTicket ticket = moveMgr.startJob(exportBatcher);
  *     exportBatcher.awaitCompletion();
  *     moveMgr.stopJob(ticket);
+ *}</pre>
  *
- * By default only document contents are retrieved.  If you would also like
+ * <p>By default only document contents are retrieved.  If you would also like
  * metadata, make sure to call {@link #withMetadataCategory withMetadataCategory}
- * to configure which categories of metadata you desire.
+ * to configure which categories of metadata you desire.</p>
  *
- * As with all the provided listeners, this listener will not meet the needs of
- * all applications but the [source code][] for it should serve as helpful sample
- * code so you can write your own custom listeners.
- *
- * [source code]: https://github.com/marklogic/java-client-api/blob/master/src/main/java/com/marklogic/client/datamovement/ExportListener.java
+ * <p>As with all the provided listeners, this listener will not meet the needs
+ * of all applications but the
+ * <a target="_blank" href="https://github.com/marklogic/java-client-api/blob/develop/src/main/java/com/marklogic/client/datamovement/ExportListener.java">source code</a>
+ * for it should serve as helpful sample code so you can write your own custom
+ * listeners.</p>
  */
 public class ExportListener implements QueryBatchListener {
   private static Logger logger = LoggerFactory.getLogger(ExportListener.class);
@@ -96,6 +98,11 @@ protected DocumentPage getDocs(QueryBatch batch) {
     }
   }
 
+  /**
+   * This implementation of initializeListener adds this instance of
+   * ExportListener to the two RetryListener's in this QueryBatcher so they
+   * will retry any batches that fail during the read request.
+   */
   @Override
   public void initializeListener(QueryBatcher queryBatcher) {
     HostAvailabilityListener hostAvailabilityListener = HostAvailabilityListener.getInstance(queryBatcher);