com.cloudant.sync.datastore

Class RevisionHistoryHelper

java.lang.Object

com.cloudant.sync.datastore.RevisionHistoryHelper

public class RevisionHistoryHelper
extends java.lang.Object

Methods to help managing document revision histories.

This class is not complete, but should bring together a set of utility methods for working with document trees.

API Status: Private - API users are discouraged from using this class as fields, method signatures, and implementation details may be subject to change

Constructor Summary

Constructors

Constructor and Description
RevisionHistoryHelper()

Method Summary

Modifier and Type	Method and Description
static MultipartAttachmentWriter	createMultipartWriter(java.util.Map<java.lang.String,java.lang.Object> revision, java.util.List<? extends Attachment> attachments, boolean shouldInline, int minRevPos) Create a MultipartAttachmentWriter object needed to subsequently write the JSON body and attachments as a MIME multipart/related stream
static java.util.List<java.lang.String>	getRevisionPath(DocumentRevs documentRevs) Returns the list of revision IDs from a DocumentRevs object.
static java.util.Map<java.lang.String,java.lang.Object>	revisionHistoryToJson(java.util.List<DocumentRevision> history) Serialise a branch's revision history, without attachments.
static java.util.Map<java.lang.String,java.lang.Object>	revisionHistoryToJson(java.util.List<DocumentRevision> history, java.util.List<? extends Attachment> attachments, boolean shouldInline, int minRevPos) Serialise a branch's revision history, in the form of a list of DocumentRevisions, into the JSON format expected by CouchDB's _bulk_docs endpoint.
static boolean	shouldInline(java.util.List<? extends Attachment> attachments, PushAttachmentsInline inlinePreference, int minRevPos) Determine whether to upload attachments inline or separately via multipart/related.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RevisionHistoryHelper

public RevisionHistoryHelper()

Method Detail

getRevisionPath

public static java.util.List<java.lang.String> getRevisionPath(DocumentRevs documentRevs)

Returns the list of revision IDs from a DocumentRevs object.

The list is (reverse) ordered, with the leaf revision ID for the branch first.

For the following input:

 {
 ...
 "_revisions": {
   "start": 4
   "ids": [
   "47d7102726fc89914431cb217ab7bace",
   "d8e1fb8127d8dd732d9ae46a6c38ae3c",
   "74e0572530e3b4cd4776616d2f591a96",
   "421ff3d58df47ea6c5e83ca65efb2fa9"
   ],
 },
 ...
 }
 

The returned value is:

 [
   "4-47d7102726fc89914431cb217ab7bace",
   "3-d8e1fb8127d8dd732d9ae46a6c38ae3c",
   "2-74e0572530e3b4cd4776616d2f591a96",
   "1-421ff3d58df47ea6c5e83ca65efb2fa9"
 ]
 

Parameters:

documentRevs - DocumentRevs object to process

Returns:

an ordered list of revision IDs for the branch, leaf node first.

See Also:

DocumentRevs

revisionHistoryToJson

public static java.util.Map<java.lang.String,java.lang.Object> revisionHistoryToJson(java.util.List<DocumentRevision> history)

Serialise a branch's revision history, without attachments. See revisionHistoryToJson(java.util.List, java.util.List, boolean, int) for details.

Parameters:

history - list of DocumentRevisions.

Returns:

JSON-serialised String suitable for sending to CouchDB's _bulk_docs endpoint.

revisionHistoryToJson

public static java.util.Map<java.lang.String,java.lang.Object> revisionHistoryToJson(java.util.List<DocumentRevision> history,
                                                                                     java.util.List<? extends Attachment> attachments,
                                                                                     boolean shouldInline,
                                                                                     int minRevPos)

Serialise a branch's revision history, in the form of a list of DocumentRevisions, into the JSON format expected by CouchDB's _bulk_docs endpoint.

Parameters:

history - list of DocumentRevisions. This should be a complete list from the revision furthest down the branch to the root.

attachments - list of Attachments, if any. This allows the _attachments dictionary to be correctly serialised. If there are no attachments, set to null.

shouldInline - whether to upload attachments inline or separately via multipart/related.

minRevPos - generation number of most recent ancestor on the remote database. If the revpos value of a given attachment is greater than minRevPos, then it is newer than the version on the remote database and must be sent. Otherwise, a stub can be sent.

Returns:

JSON-serialised String suitable for sending to CouchDB's _bulk_docs endpoint.

See Also:

DocumentRevs

shouldInline

public static boolean shouldInline(java.util.List<? extends Attachment> attachments,
                                   PushAttachmentsInline inlinePreference,
                                   int minRevPos)

Determine whether to upload attachments inline or separately via multipart/related.

If at least one attachment is determined as not being inlined according to the strategy described by inlinePreference, then all attachments are sent via multipart/related. Otherwise, all attachments are send as inline base64.

Parameters:

attachments - list of Attachments to be considered for inlining.

inlinePreference - strategy to decide whether to upload attachments inline or separately.

minRevPos - generation number of most recent ancestor on the remote database. If the revpos value of a given attachment is greater than minRevPos, then it is newer than the version on the remote database and must be sent, and therefore considered in the calculation of the return value. Otherwise, a stub will be sent and the attachment is not considered in the calculation of the return value.

Returns:

a boolean flag determining whether all attachments should be sent inline or not.

createMultipartWriter

public static MultipartAttachmentWriter createMultipartWriter(java.util.Map<java.lang.String,java.lang.Object> revision,
                                                              java.util.List<? extends Attachment> attachments,
                                                              boolean shouldInline,
                                                              int minRevPos)

Create a MultipartAttachmentWriter object needed to subsequently write the JSON body and attachments as a MIME multipart/related stream

Parameters:

revision - document revision as a Map (including _attachments metadata). This allows the JSON to be serialised into the first MIME body part

attachments - list of Attachments, if any. This allows the _attachments dictionary to be serialised into subsequent MIME body parts

shouldInline - whether to upload attachments inline or separately via multipart/related.

minRevPos - generation number of most recent ancestor on the remote database. If the revpos value of a given attachment is greater than minRevPos, then it is newer than the version on the remote database and must be sent. Otherwise, a stub can be sent.

Returns:

a MultipartAttachmentWriter object, or null if there are no attachments or all attachments are to be sent inline

See Also:

MultipartAttachmentWriter