add javadocs

Author: sammefford

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

@@ -19,13 +19,49 @@
 import com.marklogic.client.io.marker.AbstractReadHandle;
 import com.marklogic.client.io.marker.DocumentMetadataReadHandle;
 
+/** Each DocumentRecord represents one document, its uri, format, mime-type
+ *  and possibly its metadata (collections, properties, quality, and permissions).
+ *  Whether metadata is included depends on whether it was requested in the call
+ *  sent to the server. For example, to request collections metadata:
+ *  <pre>{@code
+ *JSONDocumentManager docMgr = databaseClient.newJSONDocumentManager();
+ *docMgr.setNonDocumentFormat(Format.XML);
+ *docMgr.setMetadataCategories(Metadata.COLLECTIONS);
+ *DocumentPage documents = docMgr.read("doc1.json", "doc2.json");
+ *for ( DocumentRecord record : documents ) {
+ *    String uri = record.getUri();
+ *    JacksonHandle content = record.getContent(new JacksonHandle());
+ *    DocumentMetadataHandle metadata = record.getMetadata(new DocumentMetadataHandle());
+ *    DocumentCollections collections = metadata.getCollections();
+ *    // ... do something ...
+ *}
+ *  }</pre>
+ */
 public interface DocumentRecord {
+    /** Returns the uri (unique identifier) of the document in the server */
     public String getUri();
 
+    /** Returns the format of the document in the server */
     public Format getFormat();
 
+    /** Returns the mime-type ("Content-Type" header) of the document as specified by
+     * the server (uses the server's mime-type mapping for file extensions) */
     public String getMimetype();
 
+    /**
+     * Given a handle, populates the handle with the structured metadata directly from
+     * the REST API. Depending on the nonDocumentFormat set on the DocumentManager,
+     * this will be XML or JSON format. If the nonDocumentFormat is XML, you can use
+     * DocumentMetadataHandle which offers convenient metadata access methods.
+     * @see <a href="http://docs.marklogic.com/guide/rest-dev/documents#id_63117">
+     *     REST API Dev Guide -&gt; Working with Metadata</a>
+     */
     public <T extends DocumentMetadataReadHandle> T getMetadata(T metadataHandle);
+
+    /**
+     * Given a handle, populates the handle with the document contents directly from
+     * the server (or the transformed contents if a ServerTransform was used). Use
+     * a handle that is appropriate for the {@link #getFormat format} of this document.
+     */
     public <T extends AbstractReadHandle> T getContent(T contentHandle);
 }

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

@@ -18,14 +18,60 @@
 import com.marklogic.client.io.marker.AbstractWriteHandle;
 import com.marklogic.client.io.marker.DocumentMetadataWriteHandle;
 
+/** A reflection of the write operations queued by calls to add,
+ * {@link DocumentWriteSet#add add}, {@link DocumentWriteSet#addDefault addDefault}, or
+ * {@link DocumentWriteSet#disableDefault disableDefault}.
+ */
 public interface DocumentWriteOperation {
-    public enum OperationType { METADATA_DEFAULT, DISABLE_METADATA_DEFAULT, DOCUMENT_WRITE };
+    public enum OperationType {
+        /** This write operation (REST API mime part) sets the defaults for the 
+         * rest of the request.
+         * @see <a href="http://docs.marklogic.com/guide/rest-dev/bulk#id_56498">
+         *     REST API Guide -&gt; Constructing a Metadata Part</a>
+         */
+        METADATA_DEFAULT,
+        /** This write operation (REST API mime part) clears the defaults for the
+         * rest of the request.  While this removes defaults set previously on the
+         * request, this does not completely restore server-side defaults.  For
+         * more information see the 
+         * <a href="http://docs.marklogic.com/guide/rest-dev/bulk#id_54554">
+         * REST API Guide -&gt; Example: Reverting to System Default Metadata</a>
+         */
+        DISABLE_METADATA_DEFAULT,
+        /** This write operation (REST API mime part) creates or overwrites
+         * one document and/or document metadata.
+         * @see <a href="http://docs.marklogic.com/guide/rest-dev/bulk#id_33756">
+         *     REST API Guide -&gt; Constructing a Content Part</a>
+         * @see <a href="http://docs.marklogic.com/guide/rest-dev/bulk#id_56498">
+         *     REST API Guide -&gt; Constructing a Metadata Part</a>
+         * @see <a href="http://docs.marklogic.com/guide/rest-dev/bulk#id_89876">
+         *     REST API Guide -&gt; Understanding When Metadata is Preserved or Replaced</a>
+         */
+        DOCUMENT_WRITE
+    };
 
+    /** Returns the {@link DocumentWriteOperation.OperationType} set implicitly by your call to
+     * {@link DocumentWriteSet#add add}, {@link DocumentWriteSet#addDefault addDefault}, or
+     * {@link DocumentWriteSet#disableDefault disableDefault}.
+     */
     public OperationType getOperationType();
 
+    // The uri for this document, whether set explicitly or received from the
+    // server after a write with a DocumentDescriptor.
+    /** The uri for this document if set explicitly by your call to
+     * {@link DocumentWriteSet#add(String, AbstractWriteHandle) add(String, ...)}
+     */
     public String getUri();
 
+    /** The handle with the metadata as set by your call to
+     * {@link DocumentWriteSet#add(String, DocumentMetadataWriteHandle, AbstractWriteHandle) add} or
+     * {@link DocumentWriteSet#add(DocumentDescriptor, DocumentMetadataWriteHandle, AbstractWriteHandle) add}.
+     */
     public DocumentMetadataWriteHandle getMetadata();
 
+    /** The handle with the content as set by your call to
+     * {@link DocumentWriteSet#add(String, AbstractWriteHandle) add} or
+     * {@link DocumentWriteSet#add(DocumentDescriptor, AbstractWriteHandle) add}.
+     */
     public AbstractWriteHandle getContent();
 }

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

@@ -20,17 +20,52 @@
 
 import java.util.Set;
 
+/**
+ * Builds a set of {@link DocumentWriteOperation DocumentWriteOperations} to be sent
+ * to the server through the REST API as a bulk write request.
+ * @see DocumentManager#write(DocumentWriteSet)
+ * @see <a href="http://docs.marklogic.com/guide/rest-dev/bulk#id_54649">
+ *     REST API Guide -&gt; Writing Multiple Documents</a>
+ */
 public interface DocumentWriteSet extends Set<DocumentWriteOperation> {
+    /** Sets the default metadata for this write set for all documents added after this call */
     public DocumentWriteSet addDefault(DocumentMetadataWriteHandle metadataHandle);
 
+    /** Removes the default metadata for this write set for all documents added after this call */
     public DocumentWriteSet disableDefault();
 
+    /**
+     * Adds to this write set a document with the given docId (server uri)
+     * and contents provided by the handle
+     * @param docId	the URI identifier for the document
+     * @param contentHandle	a handle for writing the content of the document
+     */
     public DocumentWriteSet add(String docId, AbstractWriteHandle contentHandle);
 
+    /**
+     * Adds to this write set a document with the given docId (server uri),
+     * metadata, and contents provided by the handle
+     * @param docId	the URI identifier for the document
+     * @param metadataHandle	a handle for writing the metadata of the document
+     * @param contentHandle	a handle for writing the content of the document
+     */
     public DocumentWriteSet add(String docId, DocumentMetadataWriteHandle metadataHandle, AbstractWriteHandle contentHandle);
 
+    /**
+     * Adds to this write set a document with the given uri template, and
+     * contents provided by the handle
+     * @param desc	a descriptor for the URI identifier, format, and mimetype of the document
+     * @param contentHandle	a handle for writing the content of the document
+     */
     public DocumentWriteSet add(DocumentDescriptor desc, AbstractWriteHandle contentHandle);
 
+    /**
+     * Adds to this write set a document with the given uri template, metadata,
+     * and contents provided by the handle
+     * @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 contentHandle	a handle for writing the content of the document
+     */
     public DocumentWriteSet add(DocumentDescriptor desc, DocumentMetadataWriteHandle metadataHandle, AbstractWriteHandle contentHandle);
 }