add lots of javadocs; clean up some existing javadocs; remove some commented code

Author: sammefford

src/main/java/com/marklogic/client/bitemporal/TemporalDocumentManager.java

@@ -20,6 +20,7 @@
 import com.marklogic.client.ResourceNotFoundException;
 import com.marklogic.client.Transaction;
 import com.marklogic.client.document.DocumentDescriptor;
+import com.marklogic.client.document.DocumentManager;
 import com.marklogic.client.document.DocumentUriTemplate;
 import com.marklogic.client.document.ServerTransform;
 import com.marklogic.client.io.marker.AbstractReadHandle;
@@ -28,14 +29,43 @@
 import com.marklogic.client.util.RequestParameters;
 
 public interface TemporalDocumentManager<R extends AbstractReadHandle, W extends AbstractWriteHandle> {
-	public DocumentDescriptor create(DocumentUriTemplate template,
+  /**
+   * Just like {@link DocumentManager#create(DocumentUriTemplate, DocumentMetadataWriteHandle,
+   * AbstractWriteHandle, ServerTransform, Transaction) create} but create document
+   * in a temporalCollection, which will enforce all the rules of
+   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * bitemporal data management</a>.
+   * @param template	the template for constructing the document uri
+   * @param metadataHandle	a handle for writing the metadata of the document
+   * @param content	an IO representation of the document content
+   * @param transform	a server transform to modify the document content
+   * @param transaction	an open transaction under which the document may have been created or deleted
+   * @param temporalCollection	the name of the temporal collection existing in the database into
+   *    which this document should be written
+   * @return the database uri that identifies the created document
+   */
+  public DocumentDescriptor create(DocumentUriTemplate template,
       DocumentMetadataWriteHandle metadataHandle,
       W contentHandle,
       ServerTransform transform,
       Transaction transaction,
       String temporalCollection)
   throws ForbiddenUserException, FailedRequestException;
 
+  /**
+   * Just like {@link DocumentManager#write(DocumentDescriptor, DocumentMetadataWriteHandle,
+   * AbstractWriteHandle, ServerTransform, Transaction) write} but write document
+   * in a temporalCollection, which will enforce all the rules of
+   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * bitemporal data management</a>.
+   * @param desc	a descriptor for the URI identifier, format, and mimetype of the document
+   * @param metadataHandle	a handle for writing the metadata of the document
+   * @param content	an IO representation of the document content
+   * @param transform	a server transform to modify the document content
+   * @param transaction	an open transaction under which the document may have been created or deleted
+   * @param temporalCollection	the name of the temporal collection existing in the database into
+   *    which this document should be written
+   */
   public void write(DocumentDescriptor desc,
       DocumentMetadataWriteHandle metadataHandle,
       W contentHandle,
@@ -44,25 +74,75 @@ public void write(DocumentDescriptor desc,
       String temporalCollection)
   throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
 
+  /**
+   * Just like {@link DocumentManager#write(String, DocumentMetadataWriteHandle,
+   * AbstractWriteHandle, ServerTransform, Transaction) write} but write document
+   * in a temporalCollection, which will enforce all the rules of
+   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * bitemporal data management</a>.
+   * @param docId	the URI identifier for the document
+   * @param metadataHandle	a handle for writing the metadata of the document
+   * @param content	an IO representation of the document content
+   * @param transform	a server transform to modify the document content
+   * @param transaction	an open transaction under which the document may have been created or deleted
+   * @param temporalCollection	the name of the temporal collection existing in the database into
+   *    which this document should be written
+   */
   public void write(String docId,
       DocumentMetadataWriteHandle metadataHandle,
       W contentHandle,
       ServerTransform transform,
       Transaction transaction,
       String temporalCollection)
   throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
-  
+
+  /**
+   * Just like {@link DocumentManager#delete(DocumentDescriptor, Transaction) delete} but delete
+   * document in a temporalCollection, which will enforce all the rules of
+   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * bitemporal data management</a>.
+   * @param desc	a descriptor for the URI identifier, format, and mimetype of the document
+   * @param transaction	an open transaction under which the document may have been created or deleted
+   * @param temporalCollection	the name of the temporal collection existing in the database in
+   *    which this document should be marked as deleted
+   */
   public void delete(DocumentDescriptor desc,
       Transaction transaction,
       String temporalCollection)
   throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
 
+  /**
+   * Just like {@link DocumentManager#delete(String, Transaction) delete} but delete
+   * document in a temporalCollection, which will enforce all the rules of
+   * <a href="http://docs.marklogic.com/8.0/guide/concepts/data-management#id_98803">
+   * bitemporal data management</a>.
+   * @param docId	the URI identifier for the document
+   * @param transaction	an open transaction under which the document may have been created or deleted
+   * @param temporalCollection	the name of the temporal collection existing in the database in
+   *    which this document should be marked as deleted
+   */
   public void delete(String docId,
       Transaction transaction,
       String temporalCollection)
   throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
-	
-	  // The following methods take a system time which is an advanced concept in bitemporal feature. 
+
+    // The following methods take a system time which is an advanced concept in bitemporal feature. 
+    //TODO: remove all extraParams
+    /**
+     * Just like {@link #create(DocumentUriTemplate, DocumentMetadataWriteHandle,
+     * AbstractWriteHandle, ServerTransform, Transaction, String) create} but create document
+     * at a specific system time
+     * @param template	the template for constructing the document uri
+     * @param metadataHandle	a handle for writing the metadata of the document
+     * @param content	an IO representation of the document content
+     * @param transform	a server transform to modify the document content
+     * @param transaction	an open transaction under which the document may have been created or deleted
+     * @param temporalCollection	the name of the temporal collection existing in the database into
+     *    which this document should be written
+     * @param systemTime	the application-specified system time with which this document will be marked
+     * @param extraParams	this param is going away in 8.0-1
+     * @return the database uri that identifies the created document
+     */
     public DocumentDescriptor create(DocumentUriTemplate template,
         DocumentMetadataWriteHandle metadataHandle,
         W contentHandle,
@@ -72,7 +152,21 @@ public DocumentDescriptor create(DocumentUriTemplate template,
         java.util.Calendar systemTime,
     		RequestParameters extraParams)
     throws ForbiddenUserException, FailedRequestException;
- 
+
+    /**
+     * Just like {@link #write(DocumentDescriptor, DocumentMetadataWriteHandle,
+     * AbstractWriteHandle, ServerTransform, Transaction, String) write} but write document
+     * at a specific system time
+     * @param desc	a descriptor for the URI identifier, format, and mimetype of the document
+     * @param metadataHandle	a handle for writing the metadata of the document
+     * @param content	an IO representation of the document content
+     * @param transform	a server transform to modify the document content
+     * @param transaction	an open transaction under which the document may have been created or deleted
+     * @param temporalCollection	the name of the temporal collection existing in the database into
+     *    which this document should be written
+     * @param systemTime	the application-specified system time with which this document will be marked
+     * @param extraParams	this param is going away in 8.0-1
+     */
     public void write(DocumentDescriptor desc,
         DocumentMetadataWriteHandle metadataHandle,
         W contentHandle,
@@ -82,7 +176,21 @@ public void write(DocumentDescriptor desc,
         java.util.Calendar systemTime,
     		RequestParameters extraParams)
     throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
- 
+
+    /**
+     * Just like {@link #write(String, DocumentMetadataWriteHandle,
+     * AbstractWriteHandle, ServerTransform, Transaction, String) write} but write document
+     * at a specific system time
+     * @param docId	the URI identifier for the document
+     * @param metadataHandle	a handle for writing the metadata of the document
+     * @param content	an IO representation of the document content
+     * @param transform	a server transform to modify the document content
+     * @param transaction	an open transaction under which the document may have been created or deleted
+     * @param temporalCollection	the name of the temporal collection existing in the database into
+     *    which this document should be written
+     * @param systemTime	the application-specified system time with which this document will be marked
+     * @param extraParams	this param is going away in 8.0-1
+     */
     public void write(String docId,
         DocumentMetadataWriteHandle metadataHandle,
         W contentHandle,
@@ -92,41 +200,34 @@ public void write(String docId,
         java.util.Calendar systemTime,
     		RequestParameters extraParams)
     throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
-    
+
+    /**
+     * Just like {@link #delete(DocumentDescriptor, Transaction, String) delete} but delete
+     * document at a specified system time
+     * @param desc	a descriptor for the URI identifier, format, and mimetype of the document
+     * @param transaction	an open transaction under which the document may have been created or deleted
+     * @param temporalCollection	the name of the temporal collection existing in the database in
+     *    which this document should be marked as deleted
+     * @param systemTime	the application-specified system time with which this document will be marked
+     */
     public void delete(DocumentDescriptor desc,
         Transaction transaction,
         String temporalCollection,
         java.util.Calendar systemTime)
     throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
- 
+
+    /**
+     * Just like {@link #delete(String, Transaction, String) delete} but delete
+     * document at a specified system time
+     * @param docId	the URI identifier for the document
+     * @param transaction	an open transaction under which the document may have been created or deleted
+     * @param temporalCollection	the name of the temporal collection existing in the database in
+     *    which this document should be marked as deleted
+     * @param systemTime	the application-specified system time with which this document will be marked
+     */
     public void delete(String docId,
         Transaction transaction,
         String temporalCollection,
         java.util.Calendar systemTime)
     throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
-    
-    /*
-    public <T extends R> T read(DocumentDescriptor desc,
-        DocumentMetadataReadHandle metadataHandle,
-        T  contentHandle,
-        ServerTransform transform,
-        Transaction transaction,
-        String temporalCollection)
-    throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
- 
-    public <T extends R> T read(String docId,
-        DocumentMetadataReadHandle metadataHandle,
-        T contentHandle,
-        ServerTransform transform,
-        Transaction transaction,
-        String temporalCollection)
-    throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
- 
-    public DocumentPage read(ServerTransform transform,
-        Transaction transaction,
-        String temporalCollection,
-        String[] uris)
-    throws ResourceNotFoundException, ForbiddenUserException,  FailedRequestException;
-    */
- 
 }