DocumentRevisionTree (sync-android 1.0.0 API)

java.lang.Object
- com.cloudant.sync.datastore.DocumentRevisionTree

```
public class DocumentRevisionTree
extends java.lang.Object
```
Describes the document tree for a single document within the datastore.

A document within a Datastore is actually a collection of trees of revisions. These trees describe the history of the document, and are the core of the MVCC data model which allows data to be safely replicated between datastores. Replication consists of copying parts of the tree in the source database that are not present in the target database to the target database.

Commonly, there will be a single tree with no branches, just a straight history. This can be represented as follows, abbreviating revision IDs to their generation numbers:
```
     1 → 2 → 3
 
```
A full revision ID looks like 1-aedlfksenef, that is the generation number combined with an opaque string which identifies this revision vs other revisions with the same generation number (see below for when this occurs).

A document can gain branches in its tree. Consider the following sequence of events:
1. A document is created in datastore A and replicated to datastore B.
2. The document is edited in both A and B.
3. Datastore B is then replicated back to A, bringing with it the changes in the document.
As described above, replication merges the parts of a document tree not in the target datastore into the target datastore. This means we now have a branched tree containing the edits from both A and B:
```
     1 → 2  → 3 → 4
      \→ 2^ → 3^
 
```
At this point we have a conflicted document: two or more branches terminating in leaf nodes which are not deleted, or active.

In this case, to resolve the conflict the application would need to:
1. Call Datastore.getDocument(String, String) to get the revisions 4 and 3^.
2. Merge these documents together in some way.
3. Save a new revision in the 4 branch using Datastore.updateDocumentFromRevision(DocumentRevision)
4. Delete the 3^ revision using Datastore.deleteDocumentFromRevision(DocumentRevision)
This process leaves us still with two branches. Because only one terminates in an active leaf, however, the document is no longer conflicted:
```
     1 →  2  → 3  → 4 → 5
      \→  2^ → 3^ → (4^ deleted)
 
```
Finally, a document may have multiple document trees. This can happen if a document with the same ID is created in two datastores, and subsequently these two datastores are replicated:
```
     1  → 2  → 3
     1* → 2* → 3* → 4*
       \→ 2^ → 3^
 
```
As an aside, this document has three conflicting revisions, which should be resolved as described above.

There can obviously be more than two roots, as a many datastores can replicate together.

At this point, it's possible to note that this class might better be called DBObjectForest. However, it's called DocumentRevisionTree because Tree is the common terminology used for the structure inside a document. As each individual tree's first revision is 1-something, one could think of the document as a single tree with an implied 0-something revision at the root.

To construct a DocumentRevisionTree, first create an empty tree. Then call add(DocumentRevision) with each DocumentRevision in ascending generation order. For DocumentRevisions with the same generation, the order they are added in should not matter; a branch will be created automatically from the DocumentRevision.getParent() property of each DocumentRevision. This implies that if a DocumentRevision that is not the root of a tree (that is, it has a parent), the parent must be added first so the tree is constructed correctly.

When a complete tree has been constructed, it's possible to work out things like the complete set of non-deleted leaf revisions (that is, the conflicted revisions for the document) and what is the current winning revision of the document.

Note: This class is not thread safe.
See Also:

Datastore.resolveConflictsForDocument(String, ConflictResolver), ConflictResolver

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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class DocumentRevisionTree.DocumentRevisionNode
A node in a document's revision tree history.

Nested Classes
Modifier and Type	Class and Description
`static class`	`DocumentRevisionTree.DocumentRevisionNode` A node in a document's revision tree history.

Constructor Summary

Constructors
Constructor and Description

DocumentRevisionTree()
Construct an empty tree.

DocumentRevisionTree(DocumentRevision documentRevision)
Construct a tree with a single root.

Constructors
Constructor and Description
`DocumentRevisionTree()` Construct an empty tree.
`DocumentRevisionTree(DocumentRevision documentRevision)` Construct a tree with a single root.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`DocumentRevisionTree`	`add(DocumentRevision documentRevision)` Adds a new `DocumentRevision` to the document.
`DocumentRevision`	`bySequence(long sequence)` Returns a `DocumentRevision` from this `DocumentRevisionTree` with a particular sequence number.
`int`	`depth(long sequence)` Returns the distance a revision is down the branch it's on.
`DocumentRevision`	`getCurrentRevision()` Returns the `DocumentRevision` that is the current winning revision for this `DocumentRevisionTree`.
`java.lang.String`	`getDocId()` Returns the document ID
`java.util.List<java.lang.String>`	`getPath(long sequence)` Returns the path as a list of revision IDs from the revision with the given sequence number to the root of the tree containing the revision.
`java.util.List<DocumentRevision>`	`getPathForNode(long sequence)` Returns the path (list of `DocumentRevision`s) from the revision with the given sequence number to the root of the tree containing the revision.
`boolean`	`hasConflicts()` Returns whether this document is conflicted.
`java.util.Set<java.lang.String>`	`leafRevisionIds()` Returns the revision IDs for the leaf revisions of this document.
`java.util.List<DocumentRevision>`	`leafRevisions()` Returns the leaf revisions
`java.util.List<DocumentRevision>`	`leafRevisions(boolean excludeDeleted)` Returns the leaf revisions
`java.util.List<DocumentRevisionTree.DocumentRevisionNode>`	`leafs()` Returns a list of the `DocumentRevisionTree.DocumentRevisionNode`s which are leaf revisions of the branches in this document
`DocumentRevision`	`lookup(java.lang.String id, java.lang.String rev)` Returns the `DocumentRevision` for a document ID and revision ID.
`DocumentRevision`	`lookupChildByRevId(DocumentRevision parentNode, java.lang.String childRevision)` Returns the child with a given revision ID of a parent `DocumentRevision`.
`DocumentRevisionTree.DocumentRevisionNode`	`root(long sequence)` Returns the root revision of this document with a given sequence number.
`java.util.Map<java.lang.Long,DocumentRevisionTree.DocumentRevisionNode>`	`roots()` Returns the root revisions of this document in a mapping of sequence number to `DocumentRevisionTree.DocumentRevisionNode`.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - DocumentRevisionTree
```
public DocumentRevisionTree()
```
    Construct an empty tree.
  - DocumentRevisionTree
```
public DocumentRevisionTree(DocumentRevision documentRevision)
```
    Construct a tree with a single root.
    
    Parameters:
    
    documentRevision - a root of the revision tree
- Method Detail
  - add
```
public DocumentRevisionTree add(DocumentRevision documentRevision)
```
    Adds a new DocumentRevision to the document.
    
    The DocumentRevision's parent, if there is one, must already be in the document tree.
    
    Parameters:
    
    documentRevision - the DocumentRevision to add
    
    Returns:
    
    DocumentRevisionTree for method chaining
  - lookup
```
public DocumentRevision lookup(java.lang.String id,
                               java.lang.String rev)
```
    Returns the DocumentRevision for a document ID and revision ID.
    
    Parameters:
    
    id - document ID
    
    rev - revision ID
    
    Returns:
    
    the DocumentRevision for the document and revision ID
  - depth
```
public int depth(long sequence)
```
    Returns the distance a revision is down the branch it's on.
    
    Parameters:
    
    sequence - sequence number to identify the revision
    
    Returns:
    
    the distance down the branch for the sequence number, -1 if the sequence number isn't present in the document.
  - lookupChildByRevId
```
public DocumentRevision lookupChildByRevId(DocumentRevision parentNode,
                                           java.lang.String childRevision)
```
    Returns the child with a given revision ID of a parent DocumentRevision.
    
    Parameters:
    
    parentNode - parent DocumentRevision
    
    childRevision - revision to look for in child nodes
    
    Returns:
    
    the child with a given revision ID of a DocumentRevision.
  - bySequence
```
public DocumentRevision bySequence(long sequence)
```
    Returns a DocumentRevision from this DocumentRevisionTree with a particular sequence number.
    
    Parameters:
    
    sequence - sequence number of the DocumentRevision
    
    Returns:
    
    the DocumentRevision with the given sequence number, null if no DocumentRevision has the given sequence number.
  - hasConflicts
```
public boolean hasConflicts()
```
    Returns whether this document is conflicted.
    
    Returns:
    
    true if there is more than one branch terminated by an active leaf revision, otherwise false
  - roots
```
public java.util.Map<java.lang.Long,DocumentRevisionTree.DocumentRevisionNode> roots()
```
    Returns the root revisions of this document in a mapping of sequence number to DocumentRevisionTree.DocumentRevisionNode.
    
    Returns:
    
    the root revisions of this document in a map
  - root
```
public DocumentRevisionTree.DocumentRevisionNode root(long sequence)
```
    Returns the root revision of this document with a given sequence number.
    
    Parameters:
    
    sequence - a sequence number
    
    Returns:
    
    the root revision of this document with a given sequence number
  - leafs
```
public java.util.List<DocumentRevisionTree.DocumentRevisionNode> leafs()
```
    Returns a list of the DocumentRevisionTree.DocumentRevisionNodes which are leaf revisions of the branches in this document
    
    Returns:
    
    list of leaf DocumentRevisionNodes
  - leafRevisionIds
```
public java.util.Set<java.lang.String> leafRevisionIds()
```
    Returns the revision IDs for the leaf revisions of this document.
    
    Returns:
    
    the set of revision IDs for the leaf revisions of this document.
  - leafRevisions
```
public java.util.List<DocumentRevision> leafRevisions()
```
    Returns the leaf revisions
    
    This is the same as calling leafRevisions(boolean) with false as the parameter
    
    Returns:
    
    a list of DocumentRevision objects.
  - leafRevisions
```
public java.util.List<DocumentRevision> leafRevisions(boolean excludeDeleted)
```
    Returns the leaf revisions
    
    Parameters:
    
    excludeDeleted - if true, exclude deleted leaf revisions from list
    
    Returns:
    
    a list of DocumentRevision objects.
  - getCurrentRevision
```
public DocumentRevision getCurrentRevision()
```
    Returns the DocumentRevision that is the current winning revision for this DocumentRevisionTree.
    
    Returns:
    
    the DocumentRevision that is the current winning revision for this DocumentRevisionTree.
  - getPathForNode
```
public java.util.List<DocumentRevision> getPathForNode(long sequence)
```
    Returns the path (list of DocumentRevisions) from the revision with the given sequence number to the root of the tree containing the revision.
    
    The list of revisions is in order of appearance in the tree, where the first revision is the given DocumentRevision and the last revision is the root of the tree.
    
    Parameters:
    
    sequence - sequence of the starting revision
    
    Returns:
    
    list of DocumentRevisions from the revision with sequence to the root of the revision's tree.
  - getPath
```
public java.util.List<java.lang.String> getPath(long sequence)
```
    Returns the path as a list of revision IDs from the revision with the given sequence number to the root of the tree containing the revision.
    
    Parameters:
    
    sequence - sequence of the starting revision
    
    Returns:
    
    list of revision IDs from the starting revision to the root of that revision's tree.
  - getDocId
```
public java.lang.String getDocId()
```
    Returns the document ID
    
    Returns:
    
    the document ID

Class DocumentRevisionTree

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DocumentRevisionTree

DocumentRevisionTree

Method Detail

add

lookup

depth

lookupChildByRevId

bySequence

hasConflicts

roots

root

leafs

leafRevisionIds

leafRevisions

leafRevisions

getCurrentRevision

getPathForNode

getPath

getDocId