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 check if a document has revisions.
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());

// In order for our edits to count as revisions, we need to declare an author and start tracking them
doc.startTrackRevisions("John Doe", new Date());
builder.write("This is revision #1. ");

// This flag corresponds to the "Track Changes" option being turned on in Microsoft Word, to track the editing manually
// done there and not the programmatic changes we are about to do here
Assert.assertFalse(doc.getTrackRevisions());

// As well as nodes in the document, revisions get referenced in this collection
Assert.assertTrue(doc.hasRevisions());
Assert.assertEquals(doc.getRevisions().getCount(), 1);

Revision revision = doc.getRevisions().get(0);
Assert.assertEquals(revision.getAuthor(), "John Doe");
Assert.assertEquals(revision.getParentNode().getText(), "This is revision #1. ");
Assert.assertEquals(revision.getRevisionType(), RevisionType.INSERTION);
Assert.assertEquals(DocumentHelper.getDateWithoutTimeUsingFormat(revision.getDateTime()), DocumentHelper.getDateWithoutTimeUsingFormat(new Date()));
Assert.assertEquals(revision.getGroup(), doc.getRevisions().getGroups().get(0));

// Deleting content also counts as a revision
// The most recent revisions are put at the start of the collection
doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).remove();
Assert.assertEquals(doc.getRevisions().get(0).getRevisionType(), RevisionType.DELETION);
Assert.assertEquals(doc.getRevisions().getCount(), 2);

// Insert revisions are treated as document text by the GetText() method before they are accepted,
// since they are still nodes with text and are in the body
Assert.assertEquals(doc.getText().trim(), "This does not count as a revision. This is revision #1.");

// Accepting the deletion revision will assimilate it into the paragraph text and remove it from the collection
doc.getRevisions().get(0).accept();
Assert.assertEquals(doc.getRevisions().getCount(), 1);

// Once the delete revision is accepted, the nodes that it concerns are removed and their text will not show up here
Assert.assertEquals(doc.getText().trim(), "This is revision #1.");

// The second insertion revision is now at index 0, which we can reject to ignore and discard it
doc.getRevisions().get(0).reject();
Assert.assertEquals(doc.getRevisions().getCount(), 0);
Assert.assertEquals(doc.getText().trim(), "");

// This takes us back to not counting changes as revisions
doc.stopTrackRevisions();

builder.writeln("This also does not count as a revision.");
Assert.assertEquals(doc.getRevisions().getCount(), 0);

doc.save(getArtifactsDir() + "Document.Revisions.docx");

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 check if a document has revisions.
        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());
        
        // In order for our edits to count as revisions, we need to declare an author and start tracking them
        doc.startTrackRevisions("John Doe", new Date());
        builder.write("This is revision #1. ");
        
        // This flag corresponds to the "Track Changes" option being turned on in Microsoft Word, to track the editing manually
        // done there and not the programmatic changes we are about to do here
        Assert.assertFalse(doc.getTrackRevisions());
        
        // As well as nodes in the document, revisions get referenced in this collection
        Assert.assertTrue(doc.hasRevisions());
        Assert.assertEquals(doc.getRevisions().getCount(), 1);
        
        Revision revision = doc.getRevisions().get(0);
        Assert.assertEquals(revision.getAuthor(), "John Doe");
        Assert.assertEquals(revision.getParentNode().getText(), "This is revision #1. ");
        Assert.assertEquals(revision.getRevisionType(), RevisionType.INSERTION);
        Assert.assertEquals(DocumentHelper.getDateWithoutTimeUsingFormat(revision.getDateTime()), DocumentHelper.getDateWithoutTimeUsingFormat(new Date()));
        Assert.assertEquals(revision.getGroup(), doc.getRevisions().getGroups().get(0));
        
        // Deleting content also counts as a revision
        // The most recent revisions are put at the start of the collection
        doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).remove();
        Assert.assertEquals(doc.getRevisions().get(0).getRevisionType(), RevisionType.DELETION);
        Assert.assertEquals(doc.getRevisions().getCount(), 2);
        
        // Insert revisions are treated as document text by the GetText() method before they are accepted,
        // since they are still nodes with text and are in the body
        Assert.assertEquals(doc.getText().trim(), "This does not count as a revision. This is revision #1.");
        
        // Accepting the deletion revision will assimilate it into the paragraph text and remove it from the collection
        doc.getRevisions().get(0).accept();
        Assert.assertEquals(doc.getRevisions().getCount(), 1);
        
        // Once the delete revision is accepted, the nodes that it concerns are removed and their text will not show up here
        Assert.assertEquals(doc.getText().trim(), "This is revision #1.");
        
        // The second insertion revision is now at index 0, which we can reject to ignore and discard it
        doc.getRevisions().get(0).reject();
        Assert.assertEquals(doc.getRevisions().getCount(), 0);
        Assert.assertEquals(doc.getText().trim(), "");
        
        // This takes us back to not counting changes as revisions
        doc.stopTrackRevisions();
        
        builder.writeln("This also does not count as a revision.");
        Assert.assertEquals(doc.getRevisions().getCount(), 0);
        
        doc.save(getArtifactsDir() + "Document.Revisions.docx");
      • getGroups

        public RevisionGroupCollection getGroups()
        
        Collection of revision groups.

        Example:

        Shows how to look through a document's revisions.
        // Open a document that contains revisions and get its revision collection
        Document doc = new Document(getMyDir() + "Document.Revisions.docx");
        RevisionCollection revisions = doc.getRevisions();
        
        // This collection itself has a collection of revision groups, which are merged sequences of adjacent revisions
        System.out.println(MessageFormat.format("{0} revision groups:", revisions.getGroups().getCount()));
        
        // We can iterate over the collection of groups and access the text that the revision concerns
        Iterator<RevisionGroup> e = revisions.getGroups().iterator();
        while (e.hasNext()) {
            RevisionGroup currentRevisionGroup = e.next();
            System.out.println(MessageFormat.format("\tGroup type \"{0}\", ", currentRevisionGroup.getRevisionType()) +
                    MessageFormat.format("author: {0}, contents: [{1}]", currentRevisionGroup.getAuthor(), currentRevisionGroup.getText().trim()));
        }
        
        // The collection of revisions is considerably larger than the condensed form we printed above,
        // depending on how many Runs the text has been segmented into during editing in Microsoft Word,
        // since each Run affected by a revision gets its own Revision object
        System.out.println(MessageFormat.format("\n{0} revisions:", revisions.getCount()));
        
        Iterator<Revision> e1 = revisions.iterator();
        
        while (e1.hasNext()) {
            Revision currentRevision = e1.next();
        
            // A StyleDefinitionChange strictly affects styles and not document nodes, so in this case the ParentStyle
            // attribute will always be used, 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 (currentRevision.getRevisionType() == RevisionType.STYLE_DEFINITION_CHANGE) {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", currentRevision.getRevisionType()) +
                        MessageFormat.format("author: {0}, style: [{1}]", currentRevision.getAuthor(), currentRevision.getParentStyle().getName()));
            } else {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", currentRevision.getRevisionType()) +
                        MessageFormat.format("author: {0}, contents: [{1}]", currentRevision.getAuthor(), currentRevision.getParentNode().getText().trim()));
            }
        }
        
        // While the collection of revision groups provides a clearer overview of all revisions that took place in the document,
        // the changes must be accepted/rejected by the revisions themselves, the RevisionCollection, or the document
        // In this case we will reject all revisions via the collection, reverting the document to its original form, which we will then save
        revisions.rejectAll();
        Assert.assertEquals(revisions.getCount(), 0);
        
        doc.save(getArtifactsDir() + "Document.RevisionCollection.docx");
      • 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 check if a document has revisions.
        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());
        
        // In order for our edits to count as revisions, we need to declare an author and start tracking them
        doc.startTrackRevisions("John Doe", new Date());
        builder.write("This is revision #1. ");
        
        // This flag corresponds to the "Track Changes" option being turned on in Microsoft Word, to track the editing manually
        // done there and not the programmatic changes we are about to do here
        Assert.assertFalse(doc.getTrackRevisions());
        
        // As well as nodes in the document, revisions get referenced in this collection
        Assert.assertTrue(doc.hasRevisions());
        Assert.assertEquals(doc.getRevisions().getCount(), 1);
        
        Revision revision = doc.getRevisions().get(0);
        Assert.assertEquals(revision.getAuthor(), "John Doe");
        Assert.assertEquals(revision.getParentNode().getText(), "This is revision #1. ");
        Assert.assertEquals(revision.getRevisionType(), RevisionType.INSERTION);
        Assert.assertEquals(DocumentHelper.getDateWithoutTimeUsingFormat(revision.getDateTime()), DocumentHelper.getDateWithoutTimeUsingFormat(new Date()));
        Assert.assertEquals(revision.getGroup(), doc.getRevisions().getGroups().get(0));
        
        // Deleting content also counts as a revision
        // The most recent revisions are put at the start of the collection
        doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).remove();
        Assert.assertEquals(doc.getRevisions().get(0).getRevisionType(), RevisionType.DELETION);
        Assert.assertEquals(doc.getRevisions().getCount(), 2);
        
        // Insert revisions are treated as document text by the GetText() method before they are accepted,
        // since they are still nodes with text and are in the body
        Assert.assertEquals(doc.getText().trim(), "This does not count as a revision. This is revision #1.");
        
        // Accepting the deletion revision will assimilate it into the paragraph text and remove it from the collection
        doc.getRevisions().get(0).accept();
        Assert.assertEquals(doc.getRevisions().getCount(), 1);
        
        // Once the delete revision is accepted, the nodes that it concerns are removed and their text will not show up here
        Assert.assertEquals(doc.getText().trim(), "This is revision #1.");
        
        // The second insertion revision is now at index 0, which we can reject to ignore and discard it
        doc.getRevisions().get(0).reject();
        Assert.assertEquals(doc.getRevisions().getCount(), 0);
        Assert.assertEquals(doc.getText().trim(), "");
        
        // This takes us back to not counting changes as revisions
        doc.stopTrackRevisions();
        
        builder.writeln("This also does not count as a revision.");
        Assert.assertEquals(doc.getRevisions().getCount(), 0);
        
        doc.save(getArtifactsDir() + "Document.Revisions.docx");
    • Method Detail

      • acceptAll

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

        Example:

        Shows how to apply the compare method to two documents and then use the results.
        Document doc1 = new Document(getMyDir() + "Document.Compare.1.doc");
        Document doc2 = new Document(getMyDir() + "Document.Compare.2.doc");
        
        // If either document has a revision, an exception will be thrown.
        if (doc1.getRevisions().getCount() == 0 && doc2.getRevisions().getCount() == 0) {
            doc1.compare(doc2, "authorName", new Date());
        }
        
        // If doc1 and doc2 are different, doc1 now has some revisions after the comparison, which can now be viewed and processed.
        for (Revision r : doc1.getRevisions())
            System.out.println(r.getRevisionType());
        
        // All the revisions in doc1 are differences between doc1 and doc2, so accepting them on doc1 transforms doc1 into doc2.
        doc1.getRevisions().acceptAll();
        
        // doc1, when saved, now resembles doc2.
        doc1.save(getArtifactsDir() + "Document.Compare.doc");
      • iterator

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

        Example:

        Shows how to look through a document's revisions.
        // Open a document that contains revisions and get its revision collection
        Document doc = new Document(getMyDir() + "Document.Revisions.docx");
        RevisionCollection revisions = doc.getRevisions();
        
        // This collection itself has a collection of revision groups, which are merged sequences of adjacent revisions
        System.out.println(MessageFormat.format("{0} revision groups:", revisions.getGroups().getCount()));
        
        // We can iterate over the collection of groups and access the text that the revision concerns
        Iterator<RevisionGroup> e = revisions.getGroups().iterator();
        while (e.hasNext()) {
            RevisionGroup currentRevisionGroup = e.next();
            System.out.println(MessageFormat.format("\tGroup type \"{0}\", ", currentRevisionGroup.getRevisionType()) +
                    MessageFormat.format("author: {0}, contents: [{1}]", currentRevisionGroup.getAuthor(), currentRevisionGroup.getText().trim()));
        }
        
        // The collection of revisions is considerably larger than the condensed form we printed above,
        // depending on how many Runs the text has been segmented into during editing in Microsoft Word,
        // since each Run affected by a revision gets its own Revision object
        System.out.println(MessageFormat.format("\n{0} revisions:", revisions.getCount()));
        
        Iterator<Revision> e1 = revisions.iterator();
        
        while (e1.hasNext()) {
            Revision currentRevision = e1.next();
        
            // A StyleDefinitionChange strictly affects styles and not document nodes, so in this case the ParentStyle
            // attribute will always be used, 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 (currentRevision.getRevisionType() == RevisionType.STYLE_DEFINITION_CHANGE) {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", currentRevision.getRevisionType()) +
                        MessageFormat.format("author: {0}, style: [{1}]", currentRevision.getAuthor(), currentRevision.getParentStyle().getName()));
            } else {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", currentRevision.getRevisionType()) +
                        MessageFormat.format("author: {0}, contents: [{1}]", currentRevision.getAuthor(), currentRevision.getParentNode().getText().trim()));
            }
        }
        
        // While the collection of revision groups provides a clearer overview of all revisions that took place in the document,
        // the changes must be accepted/rejected by the revisions themselves, the RevisionCollection, or the document
        // In this case we will reject all revisions via the collection, reverting the document to its original form, which we will then save
        revisions.rejectAll();
        Assert.assertEquals(revisions.getCount(), 0);
        
        doc.save(getArtifactsDir() + "Document.RevisionCollection.docx");
      • rejectAll

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

        Example:

        Shows how to look through a document's revisions.
        // Open a document that contains revisions and get its revision collection
        Document doc = new Document(getMyDir() + "Document.Revisions.docx");
        RevisionCollection revisions = doc.getRevisions();
        
        // This collection itself has a collection of revision groups, which are merged sequences of adjacent revisions
        System.out.println(MessageFormat.format("{0} revision groups:", revisions.getGroups().getCount()));
        
        // We can iterate over the collection of groups and access the text that the revision concerns
        Iterator<RevisionGroup> e = revisions.getGroups().iterator();
        while (e.hasNext()) {
            RevisionGroup currentRevisionGroup = e.next();
            System.out.println(MessageFormat.format("\tGroup type \"{0}\", ", currentRevisionGroup.getRevisionType()) +
                    MessageFormat.format("author: {0}, contents: [{1}]", currentRevisionGroup.getAuthor(), currentRevisionGroup.getText().trim()));
        }
        
        // The collection of revisions is considerably larger than the condensed form we printed above,
        // depending on how many Runs the text has been segmented into during editing in Microsoft Word,
        // since each Run affected by a revision gets its own Revision object
        System.out.println(MessageFormat.format("\n{0} revisions:", revisions.getCount()));
        
        Iterator<Revision> e1 = revisions.iterator();
        
        while (e1.hasNext()) {
            Revision currentRevision = e1.next();
        
            // A StyleDefinitionChange strictly affects styles and not document nodes, so in this case the ParentStyle
            // attribute will always be used, 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 (currentRevision.getRevisionType() == RevisionType.STYLE_DEFINITION_CHANGE) {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", currentRevision.getRevisionType()) +
                        MessageFormat.format("author: {0}, style: [{1}]", currentRevision.getAuthor(), currentRevision.getParentStyle().getName()));
            } else {
                System.out.println(MessageFormat.format("\tRevision type \"{0}\", ", currentRevision.getRevisionType()) +
                        MessageFormat.format("author: {0}, contents: [{1}]", currentRevision.getAuthor(), currentRevision.getParentNode().getText().trim()));
            }
        }
        
        // While the collection of revision groups provides a clearer overview of all revisions that took place in the document,
        // the changes must be accepted/rejected by the revisions themselves, the RevisionCollection, or the document
        // In this case we will reject all revisions via the collection, reverting the document to its original form, which we will then save
        revisions.rejectAll();
        Assert.assertEquals(revisions.getCount(), 0);
        
        doc.save(getArtifactsDir() + "Document.RevisionCollection.docx");