com.aspose.words

Class RevisionCollection

  • java.lang.Object
    • com.aspose.words.RevisionCollection
  • All Implemented Interfaces:
    java.lang.Iterable
    public class RevisionCollection 
    extends java.lang.Object

A collection of Revision objects that represent revisions in the document.

You do not create instances of this class directly. Use the Document.Revisions property to get revisions present in a document.

Example:

Shows how to work with revisions in a document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Normal editing of the document does not count as a revision.
builder.write("This does not count as a revision. ");

Assert.assertFalse(doc.hasRevisions());

// To register our edits as revisions, we need to declare an author, and then start tracking them.
doc.startTrackRevisions("John Doe", new Date());

builder.write("This is revision #1. ");

Assert.assertTrue(doc.hasRevisions());
Assert.assertEquals(1, doc.getRevisions().getCount());

// This flag corresponds to the "Review" -> "Tracking" -> "Track Changes" option in Microsoft Word.
// The "StartTrackRevisions" method does not affect its value,
// and the document is tracking revisions programmatically despite it having a value of "false".
// If we open this document using Microsoft Word, it will not be tracking revisions.
Assert.assertFalse(doc.getTrackRevisions());

// We have added text using the document builder, so the first revision is an insertion-type revision.
Revision revision = doc.getRevisions().get(0);
Assert.assertEquals("John Doe", revision.getAuthor());
Assert.assertEquals("This is revision #1. ", revision.getParentNode().getText());
Assert.assertEquals(RevisionType.INSERTION, revision.getRevisionType());
Assert.assertEquals(revision.getDateTime().getDate(), new Date().getDate());
Assert.assertEquals(doc.getRevisions().getGroups().get(0), revision.getGroup());

// Remove a run to create a deletion-type revision.
doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).remove();

// Adding a new revision places it at the beginning of the revision collection.
Assert.assertEquals(RevisionType.DELETION, doc.getRevisions().get(0).getRevisionType());
Assert.assertEquals(2, doc.getRevisions().getCount());

// Insert revisions show up in the document body even before we accept/reject the revision.
// Rejecting the revision will remove its nodes from the body. Conversely, nodes that make up delete revisions
// also linger in the document until we accept the revision.
Assert.assertEquals("This does not count as a revision. This is revision #1.", doc.getText().trim());

// Accepting the delete revision will remove its parent node from the paragraph text
// and then remove the collection's revision itself.
doc.getRevisions().get(0).accept();

Assert.assertEquals(1, doc.getRevisions().getCount());
Assert.assertEquals("This is revision #1.", doc.getText().trim());

builder.writeln("");
builder.write("This is revision #2.");

// Now move the node to create a moving revision type.
Node node = doc.getFirstSection().getBody().getParagraphs().get(1);
Node endNode = doc.getFirstSection().getBody().getParagraphs().get(1).getNextSibling();
Node referenceNode = doc.getFirstSection().getBody().getParagraphs().get(0);

while (node != endNode)
{
    Node nextNode = node.getNextSibling();
    doc.getFirstSection().getBody().insertBefore(node, referenceNode);
    node = nextNode;
}

Assert.assertEquals(RevisionType.MOVING, doc.getRevisions().get(0).getRevisionType());
Assert.assertEquals(8, doc.getRevisions().getCount());
Assert.assertEquals("This is revision #2.\rThis is revision #1. \rThis is revision #2.", doc.getText().trim());

// The moving revision is now at index 1. Reject the revision to discard its contents.
doc.getRevisions().get(1).reject();

Assert.assertEquals(6, doc.getRevisions().getCount());
Assert.assertEquals("This is revision #1. \rThis is revision #2.", doc.getText().trim());

Property Getters/Setters Summary
intgetCount()
Returns the number of revisions in the collection.
RevisionGroupCollectiongetGroups()
Collection of revision groups.
Revisionget(int index)
Returns a Revision at the specified index.
 
Method Summary
voidacceptAll()
Accepts all revisions in this collection.
java.util.Iterator<Revision>iterator()
Returns an enumerator object.
voidrejectAll()
Rejects all revisions in this collection.
 

    • Property Getters/Setters Detail

      • getCount

        public int getCount()
        
        Returns the number of revisions in the collection.

        Example:

        Shows how to work with revisions in a document.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Normal editing of the document does not count as a revision.
        builder.write("This does not count as a revision. ");
        
        Assert.assertFalse(doc.hasRevisions());
        
        // To register our edits as revisions, we need to declare an author, and then start tracking them.
        doc.startTrackRevisions("John Doe", new Date());
        
        builder.write("This is revision #1. ");
        
        Assert.assertTrue(doc.hasRevisions());
        Assert.assertEquals(1, doc.getRevisions().getCount());
        
        // This flag corresponds to the "Review" -> "Tracking" -> "Track Changes" option in Microsoft Word.
        // The "StartTrackRevisions" method does not affect its value,
        // and the document is tracking revisions programmatically despite it having a value of "false".
        // If we open this document using Microsoft Word, it will not be tracking revisions.
        Assert.assertFalse(doc.getTrackRevisions());
        
        // We have added text using the document builder, so the first revision is an insertion-type revision.
        Revision revision = doc.getRevisions().get(0);
        Assert.assertEquals("John Doe", revision.getAuthor());
        Assert.assertEquals("This is revision #1. ", revision.getParentNode().getText());
        Assert.assertEquals(RevisionType.INSERTION, revision.getRevisionType());
        Assert.assertEquals(revision.getDateTime().getDate(), new Date().getDate());
        Assert.assertEquals(doc.getRevisions().getGroups().get(0), revision.getGroup());
        
        // Remove a run to create a deletion-type revision.
        doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).remove();
        
        // Adding a new revision places it at the beginning of the revision collection.
        Assert.assertEquals(RevisionType.DELETION, doc.getRevisions().get(0).getRevisionType());
        Assert.assertEquals(2, doc.getRevisions().getCount());
        
        // Insert revisions show up in the document body even before we accept/reject the revision.
        // Rejecting the revision will remove its nodes from the body. Conversely, nodes that make up delete revisions
        // also linger in the document until we accept the revision.
        Assert.assertEquals("This does not count as a revision. This is revision #1.", doc.getText().trim());
        
        // Accepting the delete revision will remove its parent node from the paragraph text
        // and then remove the collection's revision itself.
        doc.getRevisions().get(0).accept();
        
        Assert.assertEquals(1, doc.getRevisions().getCount());
        Assert.assertEquals("This is revision #1.", doc.getText().trim());
        
        builder.writeln("");
        builder.write("This is revision #2.");
        
        // Now move the node to create a moving revision type.
        Node node = doc.getFirstSection().getBody().getParagraphs().get(1);
        Node endNode = doc.getFirstSection().getBody().getParagraphs().get(1).getNextSibling();
        Node referenceNode = doc.getFirstSection().getBody().getParagraphs().get(0);
        
        while (node != endNode)
        {
            Node nextNode = node.getNextSibling();
            doc.getFirstSection().getBody().insertBefore(node, referenceNode);
            node = nextNode;
        }
        
        Assert.assertEquals(RevisionType.MOVING, doc.getRevisions().get(0).getRevisionType());
        Assert.assertEquals(8, doc.getRevisions().getCount());
        Assert.assertEquals("This is revision #2.\rThis is revision #1. \rThis is revision #2.", doc.getText().trim());
        
        // The moving revision is now at index 1. Reject the revision to discard its contents.
        doc.getRevisions().get(1).reject();
        
        Assert.assertEquals(6, doc.getRevisions().getCount());
        Assert.assertEquals("This is revision #1. \rThis is revision #2.", doc.getText().trim());
      • getGroups

        public RevisionGroupCollection getGroups()
        
        Collection of revision groups.

        Example:

        Shows how to work with a document's collection of revisions.
        Document doc = new Document(getMyDir() + "Revisions.docx");
        RevisionCollection revisions = doc.getRevisions();
        
        // This collection itself has a collection of revision groups.
        // Each group is a sequence of adjacent revisions.
        System.out.println(MessageFormat.format("{0} revision groups:", revisions.getGroups().getCount()));
        
        // Iterate over the collection of groups and print the text that the revision concerns.
        Iterator<RevisionGroup> e = revisions.getGroups().iterator();
        
        while (e.hasNext()) {
            RevisionGroup revisionGroup = e.next();
        
            System.out.println(MessageFormat.format("\tGroup type \"{0}\", ", revisionGroup.getRevisionType()) +
                    MessageFormat.format("author: {0}, contents: [{1}]", revisionGroup.getAuthor(), revisionGroup.getText().trim()));
        }
        
        // Each Run that a revision affects gets a corresponding Revision object.
        // The revisions' collection is considerably larger than the condensed form we printed above,
        // depending on how many Runs we have segmented the document into during Microsoft Word editing.
        System.out.println("\n{revisions.Count} revisions:");
        
        Iterator<Revision> e1 = revisions.iterator();
        
        while (e1.hasNext()) {
            Revision revision = e1.next();
        
            // A StyleDefinitionChange strictly affects styles and not document nodes. This means the "ParentStyle"
            // property will always be in use, while the ParentNode will always be null.
            // Since all other changes affect nodes, ParentNode will conversely be in use, and ParentStyle will be null.
            if (revision.getRevisionType() == RevisionType.STYLE_DEFINITION_CHANGE) {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", revision.getRevisionType()) +
                        MessageFormat.format("author: {0}, style: [{1}]", revision.getAuthor(), revision.getParentStyle().getName()));
            } else {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", revision.getRevisionType()) +
                        MessageFormat.format("author: {0}, contents: [{1}]", revision.getAuthor(), revision.getParentNode().getText().trim()));
            }
        }
        
        // Reject all revisions via the collection, reverting the document to its original form.
        revisions.rejectAll();
        
        Assert.assertEquals(0, revisions.getCount());
      • get

        public Revision get(int index)
        
        Returns a Revision at the specified index.

        The index is zero-based.

        Negative indexes are allowed and indicate access from the back of the collection. For example -1 means the last item, -2 means the second before last and so on.

        If index is greater than or equal to the number of items in the list, this returns a null reference.

        If index is negative and its absolute value is greater than the number of items in the list, this returns a null reference.

        Parameters:
        index - An index into the collection.

        Example:

        Shows how to work with revisions in a document.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Normal editing of the document does not count as a revision.
        builder.write("This does not count as a revision. ");
        
        Assert.assertFalse(doc.hasRevisions());
        
        // To register our edits as revisions, we need to declare an author, and then start tracking them.
        doc.startTrackRevisions("John Doe", new Date());
        
        builder.write("This is revision #1. ");
        
        Assert.assertTrue(doc.hasRevisions());
        Assert.assertEquals(1, doc.getRevisions().getCount());
        
        // This flag corresponds to the "Review" -> "Tracking" -> "Track Changes" option in Microsoft Word.
        // The "StartTrackRevisions" method does not affect its value,
        // and the document is tracking revisions programmatically despite it having a value of "false".
        // If we open this document using Microsoft Word, it will not be tracking revisions.
        Assert.assertFalse(doc.getTrackRevisions());
        
        // We have added text using the document builder, so the first revision is an insertion-type revision.
        Revision revision = doc.getRevisions().get(0);
        Assert.assertEquals("John Doe", revision.getAuthor());
        Assert.assertEquals("This is revision #1. ", revision.getParentNode().getText());
        Assert.assertEquals(RevisionType.INSERTION, revision.getRevisionType());
        Assert.assertEquals(revision.getDateTime().getDate(), new Date().getDate());
        Assert.assertEquals(doc.getRevisions().getGroups().get(0), revision.getGroup());
        
        // Remove a run to create a deletion-type revision.
        doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).remove();
        
        // Adding a new revision places it at the beginning of the revision collection.
        Assert.assertEquals(RevisionType.DELETION, doc.getRevisions().get(0).getRevisionType());
        Assert.assertEquals(2, doc.getRevisions().getCount());
        
        // Insert revisions show up in the document body even before we accept/reject the revision.
        // Rejecting the revision will remove its nodes from the body. Conversely, nodes that make up delete revisions
        // also linger in the document until we accept the revision.
        Assert.assertEquals("This does not count as a revision. This is revision #1.", doc.getText().trim());
        
        // Accepting the delete revision will remove its parent node from the paragraph text
        // and then remove the collection's revision itself.
        doc.getRevisions().get(0).accept();
        
        Assert.assertEquals(1, doc.getRevisions().getCount());
        Assert.assertEquals("This is revision #1.", doc.getText().trim());
        
        builder.writeln("");
        builder.write("This is revision #2.");
        
        // Now move the node to create a moving revision type.
        Node node = doc.getFirstSection().getBody().getParagraphs().get(1);
        Node endNode = doc.getFirstSection().getBody().getParagraphs().get(1).getNextSibling();
        Node referenceNode = doc.getFirstSection().getBody().getParagraphs().get(0);
        
        while (node != endNode)
        {
            Node nextNode = node.getNextSibling();
            doc.getFirstSection().getBody().insertBefore(node, referenceNode);
            node = nextNode;
        }
        
        Assert.assertEquals(RevisionType.MOVING, doc.getRevisions().get(0).getRevisionType());
        Assert.assertEquals(8, doc.getRevisions().getCount());
        Assert.assertEquals("This is revision #2.\rThis is revision #1. \rThis is revision #2.", doc.getText().trim());
        
        // The moving revision is now at index 1. Reject the revision to discard its contents.
        doc.getRevisions().get(1).reject();
        
        Assert.assertEquals(6, doc.getRevisions().getCount());
        Assert.assertEquals("This is revision #1. \rThis is revision #2.", doc.getText().trim());
    • Method Detail

      • acceptAll

        public void acceptAll()
                      throws java.lang.Exception
        Accepts all revisions in this collection.

        Example:

        Shows how to compare documents.
        Document docOriginal = new Document();
        DocumentBuilder builder = new DocumentBuilder(docOriginal);
        builder.writeln("This is the original document.");
        
        Document docEdited = new Document();
        builder = new DocumentBuilder(docEdited);
        builder.writeln("This is the edited document.");
        
        // Comparing documents with revisions will throw an exception.
        if (docOriginal.getRevisions().getCount() == 0 && docEdited.getRevisions().getCount() == 0)
            docOriginal.compare(docEdited, "authorName", new Date());
        
        // After the comparison, the original document will gain a new revision
        // for every element that is different in the edited document.
        for (Revision r : docOriginal.getRevisions()) {
            System.out.println("Revision type: {r.RevisionType}, on a node of type \"{r.ParentNode.NodeType}\"");
            System.out.println("\tChanged text: \"{r.ParentNode.GetText()}\"");
        }
        
        // Accepting these revisions will transform the original document into the edited document.
        docOriginal.getRevisions().acceptAll();
        
        Assert.assertEquals(docOriginal.getText(), docEdited.getText());
      • iterator

        public java.util.Iterator<Revision> iterator()
        Returns an enumerator object.

        Example:

        Shows how to work with a document's collection of revisions.
        Document doc = new Document(getMyDir() + "Revisions.docx");
        RevisionCollection revisions = doc.getRevisions();
        
        // This collection itself has a collection of revision groups.
        // Each group is a sequence of adjacent revisions.
        System.out.println(MessageFormat.format("{0} revision groups:", revisions.getGroups().getCount()));
        
        // Iterate over the collection of groups and print the text that the revision concerns.
        Iterator<RevisionGroup> e = revisions.getGroups().iterator();
        
        while (e.hasNext()) {
            RevisionGroup revisionGroup = e.next();
        
            System.out.println(MessageFormat.format("\tGroup type \"{0}\", ", revisionGroup.getRevisionType()) +
                    MessageFormat.format("author: {0}, contents: [{1}]", revisionGroup.getAuthor(), revisionGroup.getText().trim()));
        }
        
        // Each Run that a revision affects gets a corresponding Revision object.
        // The revisions' collection is considerably larger than the condensed form we printed above,
        // depending on how many Runs we have segmented the document into during Microsoft Word editing.
        System.out.println("\n{revisions.Count} revisions:");
        
        Iterator<Revision> e1 = revisions.iterator();
        
        while (e1.hasNext()) {
            Revision revision = e1.next();
        
            // A StyleDefinitionChange strictly affects styles and not document nodes. This means the "ParentStyle"
            // property will always be in use, while the ParentNode will always be null.
            // Since all other changes affect nodes, ParentNode will conversely be in use, and ParentStyle will be null.
            if (revision.getRevisionType() == RevisionType.STYLE_DEFINITION_CHANGE) {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", revision.getRevisionType()) +
                        MessageFormat.format("author: {0}, style: [{1}]", revision.getAuthor(), revision.getParentStyle().getName()));
            } else {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", revision.getRevisionType()) +
                        MessageFormat.format("author: {0}, contents: [{1}]", revision.getAuthor(), revision.getParentNode().getText().trim()));
            }
        }
        
        // Reject all revisions via the collection, reverting the document to its original form.
        revisions.rejectAll();
        
        Assert.assertEquals(0, revisions.getCount());
      • rejectAll

        public void rejectAll()
                      throws java.lang.Exception
        Rejects all revisions in this collection.

        Example:

        Shows how to work with a document's collection of revisions.
        Document doc = new Document(getMyDir() + "Revisions.docx");
        RevisionCollection revisions = doc.getRevisions();
        
        // This collection itself has a collection of revision groups.
        // Each group is a sequence of adjacent revisions.
        System.out.println(MessageFormat.format("{0} revision groups:", revisions.getGroups().getCount()));
        
        // Iterate over the collection of groups and print the text that the revision concerns.
        Iterator<RevisionGroup> e = revisions.getGroups().iterator();
        
        while (e.hasNext()) {
            RevisionGroup revisionGroup = e.next();
        
            System.out.println(MessageFormat.format("\tGroup type \"{0}\", ", revisionGroup.getRevisionType()) +
                    MessageFormat.format("author: {0}, contents: [{1}]", revisionGroup.getAuthor(), revisionGroup.getText().trim()));
        }
        
        // Each Run that a revision affects gets a corresponding Revision object.
        // The revisions' collection is considerably larger than the condensed form we printed above,
        // depending on how many Runs we have segmented the document into during Microsoft Word editing.
        System.out.println("\n{revisions.Count} revisions:");
        
        Iterator<Revision> e1 = revisions.iterator();
        
        while (e1.hasNext()) {
            Revision revision = e1.next();
        
            // A StyleDefinitionChange strictly affects styles and not document nodes. This means the "ParentStyle"
            // property will always be in use, while the ParentNode will always be null.
            // Since all other changes affect nodes, ParentNode will conversely be in use, and ParentStyle will be null.
            if (revision.getRevisionType() == RevisionType.STYLE_DEFINITION_CHANGE) {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", revision.getRevisionType()) +
                        MessageFormat.format("author: {0}, style: [{1}]", revision.getAuthor(), revision.getParentStyle().getName()));
            } else {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", revision.getRevisionType()) +
                        MessageFormat.format("author: {0}, contents: [{1}]", revision.getAuthor(), revision.getParentNode().getText().trim()));
            }
        }
        
        // Reject all revisions via the collection, reverting the document to its original form.
        revisions.rejectAll();
        
        Assert.assertEquals(0, revisions.getCount());