APACHE POI: adding comment to existing word document

Question

I am working on a legacy product, in which some features need to be implemented. I am trying to use apache-poi 5.2.2 to add comments to an existing word document, based on a search criteria. Basically, if the word in the docx document matches the originalText that is defined in the action, a comment need to be added.

I have been able to add a comment to the document.

I have however been unable to add a comment range start and end to the comment (at the text that needs the comment). I am assuming that it needs some form of annotation as well. When I use for example a document with a pre-existing comment, I notice that the text at that location looks like:

<w:commentRangeStart w:id="0"/><w:r><w:rPr><w:b/><w:sz w:val="27"/></w:rPr><w:t>Júlio</w:t></w:r><w:r><w:rPr><w:b/><w:spacing w:val="-3"/><w:sz w:val="27"/></w:rPr><w:t xml:space="preserve"> </w:t></w:r><w:r><w:rPr><w:b/><w:sz w:val="27"/></w:rPr><w:t>César</w:t></w:r><w:commentRangeEnd w:id="0"/><w:r w:rsidR="00B43339"><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r><w:r>

And that the XML for the comment, which I understand is in a separate CommentsDocument looks like:

        //<xml-fragment w:id="0" w:author="<NAME OF COMMENT CREATOR>" w:date="2024-03-13T10:11:00Z" w:initials="<HERE COME THE INITIALS>" xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape">
        //  <w:p w14:paraId="4A10B938" w14:textId="77777777" w:rsidR="00B43339" w:rsidRDefault="00B43339" w:rsidP="00B43339">
        //    <w:r>
        //      <w:rPr>
        //        <w:rStyle w:val="CommentReference"/>
        //      </w:rPr>
        //      <w:annotationRef/>
        //    </w:r>
        //    <w:r>
        //      <w:rPr>
        //        <w:color w:val="000000"/>
        //        <w:sz w:val="20"/>
        //        <w:szCs w:val="20"/>
        //      </w:rPr>
        //      <w:t>This is a pre-annotation existing comment</w:t>
        //    </w:r>
        //  </w:p>
        //</xml-fragment>

Taking into account some of these posts (Adding comment to a specific word or run in docx document using Apache POI) I have tried a few things:

• Just add the comment at the run, adding the comment range start and comment range end there;
• Adding comment per paragraph.

I am guessing that things need to be a combination of both. For now I want to focus on just adding the comment on a specific word.

if(paragraph.getText().contains(action.getOriginalText())){
                //SINCE NOT THE ENTIRE PARAGRAPH NEEDS TO BE ANNOTATED, WE NEED TO LOOK AT THE RUNS INSIDE THE PARAGRAPH
                for(int runIndex = internalParagraphRunIndex; runIndex < paragraph.getRuns().size(); runIndex++) {
                    XWPFRun run = paragraph.getRuns().get(runIndex);

                    if (run.text().equals(action.getOriginalText())) {
                        

                        //THE ENTIRE RUN NEEDS TO BE ANNOTATED
                        throw new RuntimeException("Not yet implemented");
                    } else if (run.text().contains(action.getOriginalText())) {
                        System.out.println("Part of the run needs to be annotated");
                        //THE TEXT THAT NEEDS TO BE ANNOTATED IS PART OF THE RUN
                        //Getting the comments from the document
                        XWPFComments comments = wordDocument.getDocComments();

                        CTComments existingCtComments = comments.getCtComments();

                        //Creating CTComment
                        CTComment newCTComment = existingCtComments.addNewComment();
                        newCTComment.setId(getCommentId(existingCtComments));

                        String[] splittedText = splitRunTextIntoParts(run, action.getOriginalText());

                        int indexOfTextThatNeedsToBeAnnotatedInSplittedText = findLocationOfTextInSplittedText(splittedText, action.getOriginalText());

                        for (int z = 0; z < splittedText.length; z++) {
                            if (indexOfTextThatNeedsToBeAnnotatedInSplittedText == -1) {
                                throw new RuntimeException("The text that needs to be annotated is not found in the splitted run.");
                            } else {
                                if (z == indexOfTextThatNeedsToBeAnnotatedInSplittedText) {
                                    //the exact word that needs to be annotated
                                    XWPFRun runToInsert = paragraph.insertNewRun(runIndex + z);

                                    //insert part of the text of the run
                                    runToInsert.setText(splittedText[z]);

                                    paragraph.getCTP().addNewCommentRangeEnd().setId(newCTComment.getId());

                                    //add the comment reference AFTER the text
                                    runToInsert.getCTR().addNewCommentReference().setId(newCTComment.getId());

                                    //TODO: remove styling
                                    runToInsert.setBold(true);

                                } else if (z == indexOfTextThatNeedsToBeAnnotatedInSplittedText - 1) {

                                    XWPFRun runToInsert = paragraph.insertNewRun(runIndex + z);

                                    //insert part of the text of the run
                                    runToInsert.setText(splittedText[z]);

                                    //add the range start after the text of the run
                                    CTMarkupRange rangeStartMarkupRange = paragraph.getCTP().addNewCommentRangeStart();
                                    rangeStartMarkupRange.setId(newCTComment.getId());
                                    newCTComment.setCommentRangeStartArray(new CTMarkupRange[]{rangeStartMarkupRange});

                                    //TODO: remove styling
                                    runToInsert.setItalic(true);


                                } else if (z == indexOfTextThatNeedsToBeAnnotatedInSplittedText + 1) {


                                    //add the range end before the text of the run
                                    CTMarkupRange rangeEndeMarkupRange = paragraph.getCTP().addNewCommentRangeEnd();
                                    rangeEndeMarkupRange.setId(newCTComment.getId());

                                    newCTComment.setCommentRangeEndArray(new CTMarkupRange[]{rangeEndeMarkupRange});
                                    //newCTComment.setCommentRangeEndArray(new CTMarkupRange[]{rangeEndeMarkupRange});

                                    //insert new run
                                    XWPFRun runToInsert = paragraph.insertNewRun(runIndex + z);
                                    //insert part of the text of the run
                                    runToInsert.setText(splittedText[z]);

                                    //TODO: remove styling
                                    runToInsert.setUnderline(UnderlinePatterns.SINGLE);
                                }
                            }
                        }

                        //remove original run
                        paragraph.removeRun(runIndex + splittedText.length); //the  new runs are put in front of the old run

                        //Creating the new XWPFComment based on the CTComment
                        XWPFComment newComment = new XWPFComment(newCTComment, comments);
                        newComment.setAuthor("Teradactor");
                        newComment.setDate(new GregorianCalendar());
                        newComment.setInitials("TD");
                        newComment.createParagraph().createRun().setText(action.getAnnotationText());


                        comments.createComment(BigInteger.valueOf(Long.parseLong(newComment.getId())));


                        setParagraphIndex(paragraphToLookAt);
                        setInternalParagraphRunIndex(runIndex + 3); // the next time we want to start from the runs after th, since this one is already annotated
                        setActionFound(true);
                        //because we are splitting the run into several runs, we need to decrease the index of the tnsmap text

                        break;

                    }

This method adds succesfully a comment reference after the word that needs to be annotated. I can also see that the text before or after the word that needs to be annotated is styled (italic or underline) and that the word itself is bold. However, there is no proper comment reference on the wordt itself. If an annotation reference is necessary, it would be good to know and how to set it up.

Answer 1

So your main question is:

How to comment single text parts in an existing Word document either being single text runs already or being within long text runs?

This is very broad. Too broad to answer here. To get single text parts as own text runs see How to Highlight Replaced Word Using Apache POI. Please read The value "name" and "surname" aren't read apache poi and Apache POI: ${my_placeholder} is treated as three different runs too as this provides a bug fix for XWPFParagraph.searchText.

Aside the question of how to get single text parts as own text runs, the question how to comment single text runs can be answered so:

Each commented text run looks like so in word/document.xml:

...
<w:commentRangeStart w:id="1"/>
<w:r>
 <w:rPr>
 ...
 </w:rPr>
 <w:t>run text</w:t>
</w:r>
<w:commentRangeEnd w:id="1"/>
<w:r>
 <w:commentReference w:id="1"/>
</w:r>
..

There is a commentRangeStart immediately before the text run and a commentRangeEnd immediately after the text run immediately followed by a text run containing the commentReference only.

To create this we need using the org.openxmlformats.schemas.wordprocessingml.x2006.main.* classes and native XML methods like org.apache.xmlbeans.XmlCursor as Apache POI does not provide methods to do this in XWPF.

Complete example which simply comments each single text run to show that it works.

import java.io.*;

import org.apache.poi.xwpf.usermodel.*;

import org.openxmlformats.schemas.wordprocessingml.x2006.main.*;
import org.apache.xmlbeans.XmlCursor;

import java.math.BigInteger;
import java.util.GregorianCalendar;
import java.util.Locale;

public class WordCommentTextRuns {

 //method to get or create the CommentsDocument /word/comments.xml in the *.docx ZIP archive  
 private static XWPFComments createCommentsDocument(XWPFDocument document) throws Exception {
  XWPFComments commentsDocument = null;
  //trying to get the CommentsDocument
  commentsDocument = document.getDocComments();
  //create a new CommentsDocument if there is not one already
  if (commentsDocument == null) {
   commentsDocument = document.createComments();  
   System.out.println("comments document created");
  }
  return commentsDocument;
 }

 //method to get the next comment Id from CTComments
 private static BigInteger getCommentId(CTComments comments) {
  BigInteger cId = BigInteger.ZERO;
  for (CTComment ctComment : comments.getCommentList()) {
   if (ctComment.getId().compareTo(cId) == 1) {
    cId = ctComment.getId();
   }
  }
  cId = cId.add(BigInteger.ONE);
  return cId;
 }

 //method to set CommentRangeStart before text run
 private static CTMarkupRange insertCommentRangeStartBefore(XWPFRun run) {
  String uri = CTMarkupRange.type.getName().getNamespaceURI();
  String localPart = "commentRangeStart";
  XmlCursor cursor = run.getCTR().newCursor();
  cursor.beginElement(localPart, uri);
  cursor.toParent();
  CTMarkupRange commentRangeStart = (CTMarkupRange)cursor.getObject();
  return commentRangeStart;  
 }
 
 //method to set CommentRangeEnd after text run
 private static CTMarkupRange insertCommentRangeEndAfter(XWPFRun run) {
  String uri = CTMarkupRange.type.getName().getNamespaceURI();
  String localPart = "commentRangeEnd";
  XmlCursor cursor = run.getCTR().newCursor();
  cursor.toEndToken();
  cursor.toNextToken();
  cursor.beginElement(localPart, uri);
  cursor.toParent();
  CTMarkupRange commentRangeStart = (CTMarkupRange)cursor.getObject();
  return commentRangeStart;  
 }

 //method to set CommentReference after CommentRangeEnd 
 private static void insertCommentReferenceAfter(CTMarkupRange commentRangeEnd, BigInteger cId) {
  String uri = CTR.type.getName().getNamespaceURI();
  String localPart = "r";
  XmlCursor cursor = commentRangeEnd.newCursor();
  cursor.toEndToken();
  cursor.toNextToken();
  cursor.beginElement(localPart, uri);
  cursor.toParent();
  CTR ctr = (CTR)cursor.getObject();
  ctr.addNewCommentReference().setId(cId);
 }

 //method to comment single text runs
 private static void commentTextRun(XWPFRun run, CTComments comments, String commentText) {
  CTComment ctComment;
  
  //comment for the run
  BigInteger cId = getCommentId(comments);
  ctComment = comments.addNewComment();
  ctComment.setAuthor("Axel Ríchter");
  ctComment.setInitials("AR");
  ctComment.setDate(new GregorianCalendar(Locale.US));
  ctComment.addNewP().addNewR().addNewT().setStringValue(commentText);
  ctComment.setId(cId);

  //set CommentRangeStart
  CTMarkupRange commentRangeStart = insertCommentRangeStartBefore(run);
  commentRangeStart.setId(cId);

  //set CommentRangeEnd and CommentReference
  CTMarkupRange commentRangeEnd = insertCommentRangeEndAfter(run);
  commentRangeEnd.setId(cId);
  insertCommentReferenceAfter(commentRangeEnd, cId); 
 }

 public static void main(String[] args) throws Exception {

  XWPFDocument document = new XWPFDocument(new FileInputStream("./WordDocument.docx"));

  XWPFComments commentsDocument = createCommentsDocument(document);
  CTComments comments = commentsDocument.getCtComments();
    
  for (XWPFParagraph paragraph : document.getParagraphs()) {
   for (XWPFRun run : paragraph.getRuns()) {
    // simply comment each single text run to show that it works
    commentTextRun(run, comments, "Comment text");
   }
  }

  FileOutputStream out = new FileOutputStream("./WordDocumentWithComments.docx");
  document.write(out);
  out.close();
  document.close();

 }
}