Class XWPFDocument

All Implemented Interfaces:
Closeable, AutoCloseable, Document, IBody

public class XWPFDocument extends POIXMLDocument implements Document, IBody

High(ish) level class for working with .docx files.

This class tries to hide some of the complexity of the underlying file format, but as it's not a mature and stable API yet, certain parts of the XML structure come through. You'll therefore almost certainly need to refer to the OOXML specifications from http://www.ecma-international.org/publications/standards/Ecma-376.htm at some point in your use.

  • Field Details

  • Constructor Details

  • Method Details

    • newPackage

      protected static OPCPackage newPackage()
      Create a new WordProcessingML package and setup the default minimal content
    • onDocumentRead

      protected void onDocumentRead() throws IOException
      Description copied from class: POIXMLDocumentPart
      Fired when a package part is read
      Overrides:
      onDocumentRead in class POIXMLDocumentPart
      Throws:
      IOException - a subclass may throw an IOException when a document is read
    • onDocumentCreate

      protected void onDocumentCreate()
      Create a new CTWorkbook with all values set to default
      Overrides:
      onDocumentCreate in class POIXMLDocumentPart
    • getDocument

      @Internal public org.openxmlformats.schemas.wordprocessingml.x2006.main.CTDocument1 getDocument()
      Returns the low level document base object
    • getBodyElements

      public List<IBodyElement> getBodyElements()
      returns an Iterator with paragraphs and tables
      Specified by:
      getBodyElements in interface IBody
      See Also:
    • getBodyElementsIterator

      public Iterator<IBodyElement> getBodyElementsIterator()
    • getParagraphs

      public List<XWPFParagraph> getParagraphs()
      Description copied from interface: IBody
      Returns the paragraph(s) that holds the text of the header or footer.
      Specified by:
      getParagraphs in interface IBody
      See Also:
    • getTables

      public List<XWPFTable> getTables()
      Description copied from interface: IBody
      Return the table(s) that holds the text of the IBodyPart, for complex cases where a paragraph isn't used.
      Specified by:
      getTables in interface IBody
      See Also:
    • getCharts

      public List<XWPFChart> getCharts()
      Returns:
      list of XWPFCharts in this document
    • getTableArray

      public XWPFTable getTableArray(int pos)
      Description copied from interface: IBody
      Returns the table at position pos
      Specified by:
      getTableArray in interface IBody
      See Also:
    • getFooterList

      public List<XWPFFooter> getFooterList()
      Returns:
      the list of footers
    • getFooterArray

      public XWPFFooter getFooterArray(int pos)
    • getHeaderList

      public List<XWPFHeader> getHeaderList()
      Returns:
      the list of headers
    • getHeaderArray

      public XWPFHeader getHeaderArray(int pos)
    • getTblStyle

      public String getTblStyle(XWPFTable table)
    • getHyperlinkByID

      public XWPFHyperlink getHyperlinkByID(String id)
    • getFootnoteByID

      public XWPFFootnote getFootnoteByID(int id)
    • getEndnoteByID

      public XWPFEndnote getEndnoteByID(int id)
    • getFootnotes

      public List<XWPFFootnote> getFootnotes()
    • getHyperlinks

      public XWPFHyperlink[] getHyperlinks()
    • getCommentByID

      public XWPFComment getCommentByID(String id)
    • getComments

      public XWPFComment[] getComments()
    • getPartById

      public PackagePart getPartById(String id)
      Get the document part that's defined as the given relationship of the core document.
    • getHeaderFooterPolicy

      public XWPFHeaderFooterPolicy getHeaderFooterPolicy()
      Returns the policy on headers and footers, which also provides a way to get at them.
    • createHeaderFooterPolicy

      public XWPFHeaderFooterPolicy createHeaderFooterPolicy()
    • createHeader

      public XWPFHeader createHeader(HeaderFooterType type)
      Create a header of the given type
      Parameters:
      type - HeaderFooterType enum
      Returns:
      object of type XWPFHeader
    • createFooter

      public XWPFFooter createFooter(HeaderFooterType type)
      Create a footer of the given type
      Parameters:
      type - HeaderFooterType enum
      Returns:
      object of type XWPFFooter
    • getStyle

      @Internal public org.openxmlformats.schemas.wordprocessingml.x2006.main.CTStyles getStyle() throws org.apache.xmlbeans.XmlException, IOException
      Returns the styles object used
      Throws:
      org.apache.xmlbeans.XmlException
      IOException
    • getAllEmbeddedParts

      public List<PackagePart> getAllEmbeddedParts() throws OpenXML4JException
      Get the document's embedded files.
      Specified by:
      getAllEmbeddedParts in class POIXMLDocument
      Returns:
      the document's embedded files
      Throws:
      OpenXML4JException - if the embedded parts can't be determined
    • getParagraphPos

      public int getParagraphPos(int pos)
      Look up the paragraph at the specified position in the body elements list and return this paragraphs position in the paragraphs list
      Parameters:
      pos - The position of the relevant paragraph in the body elements list
      Returns:
      the position of the paragraph in the paragraphs list, if there is a paragraph at the position in the bodyelements list. Else it will return -1
    • getTablePos

      public int getTablePos(int pos)
      get with the position of a table in the bodyelement array list the position of this table in the table array list
      Parameters:
      pos - position of the table in the bodyelement array list
      Returns:
      if there is a table at the position in the bodyelement array list, else it will return null.
    • insertNewParagraph

      public XWPFParagraph insertNewParagraph(org.apache.xmlbeans.XmlCursor cursor)
      Add a new paragraph at position of the cursor. The cursor must be on the XmlCursor.TokenType.START tag of an subelement of the documents body. When this method is done, the cursor passed as parameter points to the XmlCursor.TokenType.END of the newly inserted paragraph.
      Specified by:
      insertNewParagraph in interface IBody
      Parameters:
      cursor - The cursor-position where the new paragraph should be added.
      Returns:
      the XWPFParagraph object representing the newly inserted CTP object
    • insertNewTbl

      public XWPFTable insertNewTbl(org.apache.xmlbeans.XmlCursor cursor)
      Description copied from interface: IBody
      inserts a new Table at the cursor position.
      Specified by:
      insertNewTbl in interface IBody
    • getPosOfParagraph

      public int getPosOfParagraph(XWPFParagraph p)
      Get the position of the paragraph, within the list of all the body elements.
      Parameters:
      p - The paragraph to find
      Returns:
      The location, or -1 if the paragraph couldn't be found
    • getPosOfTable

      public int getPosOfTable(XWPFTable t)
      Get the position of the table, within the list of all the body elements.
      Parameters:
      t - The table to find
      Returns:
      The location, or -1 if the table couldn't be found
    • commit

      protected void commit() throws IOException
      commit and saves the document
      Overrides:
      commit in class POIXMLDocumentPart
      Throws:
      IOException - a subclass may throw an IOException if the changes can't be committed
    • createParagraph

      public XWPFParagraph createParagraph()
      Appends a new paragraph to this document
      Returns:
      a new paragraph
    • createNumbering

      public XWPFNumbering createNumbering()
      Creates an empty numbering if one does not already exist and sets the numbering member
      Returns:
      numbering
    • createStyles

      public XWPFStyles createStyles()
      Creates an empty styles for the document if one does not already exist
      Returns:
      styles
    • createFootnotes

      public XWPFFootnotes createFootnotes()
      Creates an empty footnotes element for the document if one does not already exist
      Returns:
      footnotes
    • addFootnote

      @Internal public XWPFFootnote addFootnote(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTFtnEdn note)
      Add a CTFtnEdn footnote to the document.
      Parameters:
      note - CTFtnEnd to be added.
      Returns:
      New XWPFFootnote
    • addEndnote

      @Internal public XWPFEndnote addEndnote(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTFtnEdn note)
      Add a CTFtnEdn endnote to the document.
      Parameters:
      note - CTFtnEnd to be added.
      Returns:
      New XWPFEndnote
    • removeBodyElement

      public boolean removeBodyElement(int pos)
      remove a BodyElement from bodyElements array list
      Parameters:
      pos -
      Returns:
      true if removing was successfully, else return false
    • setParagraph

      public void setParagraph(XWPFParagraph paragraph, int pos)
      copies content of a paragraph to a existing paragraph in the list paragraphs at position pos
      Parameters:
      paragraph -
      pos -
    • getLastParagraph

      public XWPFParagraph getLastParagraph()
      Returns:
      the LastParagraph of the document
    • createTable

      public XWPFTable createTable()
      Create an empty table with one row and one column as default.
      Returns:
      a new table
    • createTable

      public XWPFTable createTable(int rows, int cols)
      Create an empty table with a number of rows and cols specified
      Parameters:
      rows -
      cols -
      Returns:
      table
    • createTOC

      public void createTOC()
    • setTable

      public void setTable(int pos, XWPFTable table)
      Replace content of table in array tables at position pos with a
      Parameters:
      pos -
      table -
    • isEnforcedProtection

      public boolean isEnforcedProtection()
      Verifies that the documentProtection tag in settings.xml file
      specifies that the protection is enforced (w:enforcement="1")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="readOnly" w:enforcement="1"/>
       
      Returns:
      true if documentProtection is enforced with option any
    • isEnforcedReadonlyProtection

      public boolean isEnforcedReadonlyProtection()
      Verifies that the documentProtection tag in settings.xml file
      specifies that the protection is enforced (w:enforcement="1")
      and that the kind of protection is readOnly (w:edit="readOnly")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="readOnly" w:enforcement="1"/>
       
      Returns:
      true if documentProtection is enforced with option readOnly
    • isEnforcedFillingFormsProtection

      public boolean isEnforcedFillingFormsProtection()
      Verifies that the documentProtection tag in settings.xml file
      specifies that the protection is enforced (w:enforcement="1")
      and that the kind of protection is forms (w:edit="forms")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="forms" w:enforcement="1"/>
       
      Returns:
      true if documentProtection is enforced with option forms
    • isEnforcedCommentsProtection

      public boolean isEnforcedCommentsProtection()
      Verifies that the documentProtection tag in settings.xml file
      specifies that the protection is enforced (w:enforcement="1")
      and that the kind of protection is comments (w:edit="comments")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="comments" w:enforcement="1"/>
       
      Returns:
      true if documentProtection is enforced with option comments
    • isEnforcedTrackedChangesProtection

      public boolean isEnforcedTrackedChangesProtection()
      Verifies that the documentProtection tag in settings.xml file
      specifies that the protection is enforced (w:enforcement="1")
      and that the kind of protection is trackedChanges (w:edit="trackedChanges")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="trackedChanges" w:enforcement="1"/>
       
      Returns:
      true if documentProtection is enforced with option trackedChanges
    • isEnforcedUpdateFields

      public boolean isEnforcedUpdateFields()
    • enforceReadonlyProtection

      public void enforceReadonlyProtection()
      Enforces the readOnly protection.
      In the documentProtection tag inside settings.xml file,
      it sets the value of enforcement to "1" (w:enforcement="1")
      and the value of edit to readOnly (w:edit="readOnly")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="readOnly" w:enforcement="1"/>
       
    • enforceReadonlyProtection

      public void enforceReadonlyProtection(String password, HashAlgorithm hashAlgo)
      Enforces the readOnly protection with a password.

      sample snippet from settings.xml
         <w:documentProtection w:edit="readOnly" w:enforcement="1"
             w:cryptProviderType="rsaAES" w:cryptAlgorithmClass="hash"
             w:cryptAlgorithmType="typeAny" w:cryptAlgorithmSid="14"
             w:cryptSpinCount="100000" w:hash="..." w:salt="...."
         />
       
      Parameters:
      password - the plaintext password, if null no password will be applied
      hashAlgo - the hash algorithm - only md2, m5, sha1, sha256, sha384 and sha512 are supported. if null, it will default default to sha1
    • enforceFillingFormsProtection

      public void enforceFillingFormsProtection()
      Enforce the Filling Forms protection.
      In the documentProtection tag inside settings.xml file,
      it sets the value of enforcement to "1" (w:enforcement="1")
      and the value of edit to forms (w:edit="forms")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="forms" w:enforcement="1"/>
       
    • enforceFillingFormsProtection

      public void enforceFillingFormsProtection(String password, HashAlgorithm hashAlgo)
      Enforce the Filling Forms protection.

      sample snippet from settings.xml
         <w:documentProtection w:edit="forms" w:enforcement="1"
             w:cryptProviderType="rsaAES" w:cryptAlgorithmClass="hash"
             w:cryptAlgorithmType="typeAny" w:cryptAlgorithmSid="14"
             w:cryptSpinCount="100000" w:hash="..." w:salt="...."
         />
       
      Parameters:
      password - the plaintext password, if null no password will be applied
      hashAlgo - the hash algorithm - only md2, m5, sha1, sha256, sha384 and sha512 are supported. if null, it will default default to sha1
    • enforceCommentsProtection

      public void enforceCommentsProtection()
      Enforce the Comments protection.
      In the documentProtection tag inside settings.xml file,
      it sets the value of enforcement to "1" (w:enforcement="1")
      and the value of edit to comments (w:edit="comments")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="comments" w:enforcement="1"/>
       
    • enforceCommentsProtection

      public void enforceCommentsProtection(String password, HashAlgorithm hashAlgo)
      Enforce the Comments protection.

      sample snippet from settings.xml
         <w:documentProtection w:edit="comments" w:enforcement="1"
             w:cryptProviderType="rsaAES" w:cryptAlgorithmClass="hash"
             w:cryptAlgorithmType="typeAny" w:cryptAlgorithmSid="14"
             w:cryptSpinCount="100000" w:hash="..." w:salt="...."
         />
       
      Parameters:
      password - the plaintext password, if null no password will be applied
      hashAlgo - the hash algorithm - only md2, m5, sha1, sha256, sha384 and sha512 are supported. if null, it will default default to sha1
    • enforceTrackedChangesProtection

      public void enforceTrackedChangesProtection()
      Enforce the Tracked Changes protection.
      In the documentProtection tag inside settings.xml file,
      it sets the value of enforcement to "1" (w:enforcement="1")
      and the value of edit to trackedChanges (w:edit="trackedChanges")

      sample snippet from settings.xml
           <w:settings  ... >
               <w:documentProtection w:edit="trackedChanges" w:enforcement="1"/>
       
    • enforceTrackedChangesProtection

      public void enforceTrackedChangesProtection(String password, HashAlgorithm hashAlgo)
      Enforce the Tracked Changes protection.

      sample snippet from settings.xml
         <w:documentProtection w:edit="trackedChanges" w:enforcement="1"
             w:cryptProviderType="rsaAES" w:cryptAlgorithmClass="hash"
             w:cryptAlgorithmType="typeAny" w:cryptAlgorithmSid="14"
             w:cryptSpinCount="100000" w:hash="..." w:salt="...."
         />
       
      Parameters:
      password - the plaintext password, if null no password will be applied
      hashAlgo - the hash algorithm - only md2, m5, sha1, sha256, sha384 and sha512 are supported. if null, it will default default to sha1
    • validateProtectionPassword

      public boolean validateProtectionPassword(String password)
      Validates the existing password
      Parameters:
      password -
      Returns:
      true, only if password was set and equals, false otherwise
    • removeProtectionEnforcement

      public void removeProtectionEnforcement()
      Remove protection enforcement.
      In the documentProtection tag inside settings.xml file
      it sets the value of enforcement to "0" (w:enforcement="0")
    • enforceUpdateFields

      public void enforceUpdateFields()
      Enforces fields update on document open (in Word). In the settings.xml file
      sets the updateSettings value to true (w:updateSettings w:val="true")

      NOTICES:

      • Causing Word to ask on open: "This document contains fields that may refer to other files. Do you want to update the fields in this document?" (if "Update automatic links at open" is enabled)
      • Flag is removed after saving with changes in Word
    • isTrackRevisions

      public boolean isTrackRevisions()
      Check if revision tracking is turned on.
      Returns:
      true if revision tracking is turned on
    • setTrackRevisions

      public void setTrackRevisions(boolean enable)
      Enable or disable revision tracking.
      Parameters:
      enable - true to turn on revision tracking, false to turn off revision tracking
    • getZoomPercent

      public long getZoomPercent()
      Returns the current zoom factor in percent values, i.e. 100 is normal zoom.
      Returns:
      A percent value denoting the current zoom setting of this document.
    • setZoomPercent

      public void setZoomPercent(long zoomPercent)
      Set the zoom setting as percent value, i.e. 100 is normal zoom.
      Parameters:
      zoomPercent - A percent value denoting the zoom setting for this document.
    • getEvenAndOddHeadings

      public boolean getEvenAndOddHeadings()
      Returns the even-and-odd-headings setting
      Returns:
      True or false indicating whether or not separate even and odd headings is turned on.
    • setEvenAndOddHeadings

      public void setEvenAndOddHeadings(boolean enable)
      Sets the even-and-odd-headings setting
      Parameters:
      enable - Set to true to turn on separate even and odd headings.
    • getMirrorMargins

      public boolean getMirrorMargins()
      Returns the mirror margins setting
      Returns:
      True or false indicating whether or not mirror margins is turned on.
    • setMirrorMargins

      public void setMirrorMargins(boolean enable)
      Sets the mirror margins setting
      Parameters:
      enable - Set to true to turn on mirror margins.
    • insertTable

      public void insertTable(int pos, XWPFTable table)
      inserts an existing XWPFTable to the arrays bodyElements and tables
      Specified by:
      insertTable in interface IBody
      Parameters:
      pos -
      table -
    • getAllPictures

      public List<XWPFPictureData> getAllPictures()
      Returns all Pictures, which are referenced from the document itself.
      Returns:
      a List of XWPFPictureData. The returned List is unmodifiable. Use #a
    • getAllPackagePictures

      public List<XWPFPictureData> getAllPackagePictures()
      Returns:
      all Pictures in this package
    • addPictureData

      public String addPictureData(byte[] pictureData, int format) throws InvalidFormatException
      Throws:
      InvalidFormatException
    • addPictureData

      public String addPictureData(InputStream is, int format) throws InvalidFormatException
      Throws:
      InvalidFormatException
    • getNextPicNameNumber

      public int getNextPicNameNumber(int format) throws InvalidFormatException
      get the next free ImageNumber
      Parameters:
      format -
      Returns:
      the next free ImageNumber
      Throws:
      InvalidFormatException - If the format of the picture is not known.
    • getPictureDataByID

      public XWPFPictureData getPictureDataByID(String blipID)
      returns the PictureData by blipID
      Parameters:
      blipID -
      Returns:
      XWPFPictureData of a specificID
    • getNumbering

      public XWPFNumbering getNumbering()
      getNumbering
      Returns:
      numbering
    • getStyles

      public XWPFStyles getStyles()
      get Styles
      Returns:
      styles for this document
    • getParagraph

      public XWPFParagraph getParagraph(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP p)
      get the paragraph with the CTP class p
      Specified by:
      getParagraph in interface IBody
      Parameters:
      p -
      Returns:
      the paragraph with the CTP class p
    • getTable

      public XWPFTable getTable(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTTbl ctTbl)
      get a table by its CTTbl-Object
      Specified by:
      getTable in interface IBody
      Parameters:
      ctTbl -
      Returns:
      a table by its CTTbl-Object or null
      See Also:
    • getTablesIterator

      public Iterator<XWPFTable> getTablesIterator()
    • getParagraphsIterator

      public Iterator<XWPFParagraph> getParagraphsIterator()
    • getParagraphArray

      public XWPFParagraph getParagraphArray(int pos)
      Returns the paragraph that of position pos
      Specified by:
      getParagraphArray in interface IBody
      See Also:
    • getPart

      public POIXMLDocumentPart getPart()
      returns the Part, to which the body belongs, which you need for adding relationship to other parts Actually it is needed of the class XWPFTableCell. Because you have to know to which part the tableCell belongs.
      Specified by:
      getPart in interface IBody
      Returns:
      the Part, to which the body belongs
      See Also:
    • getPartType

      public BodyType getPartType()
      get the PartType of the body, for example DOCUMENT, HEADER, FOOTER, FOOTNOTE,
      Specified by:
      getPartType in interface IBody
      Returns:
      the PartType of the body
      See Also:
    • getTableCell

      public XWPFTableCell getTableCell(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTTc cell)
      get the TableCell which belongs to the TableCell
      Specified by:
      getTableCell in interface IBody
      Parameters:
      cell -
    • getXWPFDocument

      public XWPFDocument getXWPFDocument()
      Description copied from interface: IBody
      Return XWPFDocument
      Specified by:
      getXWPFDocument in interface IBody
    • createChart

      public XWPFChart createChart() throws InvalidFormatException, IOException
      This method is used to create template for chart XML no need to read MS-Word file and modify charts
      Returns:
      This method return object of XWPFChart Object with default height and width
      Throws:
      InvalidFormatException
      IOException
      Since:
      POI 4.0.0
    • createChart

      public XWPFChart createChart(int width, int height) throws InvalidFormatException, IOException
      This method is used to create template for chart XML no need to read MS-Word file and modify charts
      Parameters:
      width - width of chart in document
      height - height of chart in document
      Returns:
      This method return object of XWPFChart
      Throws:
      InvalidFormatException
      IOException
      Since:
      POI 4.0.0
    • createFootnote

      public XWPFFootnote createFootnote()
      Create a new footnote and add it to the document.
      Returns:
      New XWPFFootnote.
      Since:
      4.0.0
    • removeFootnote

      public boolean removeFootnote(int pos)
      Remove the specified footnote if present.
      Parameters:
      pos - Array position of the footnote to be removed.
      Returns:
      True if the footnote was removed.
      Since:
      4.0.0
    • createEndnote

      public XWPFEndnote createEndnote()
      Create a new end note and add it to the document.
      Returns:
      New XWPFEndnote.
      Since:
      4.0.0
    • createEndnotes

      public XWPFEndnotes createEndnotes()
    • getEndnotes

      public List<XWPFEndnote> getEndnotes()
      Gets the list of end notes for the document.
      Returns:
      List, possibly empty, of XWPFEndnotes.
    • removeEndnote

      public boolean removeEndnote(int pos)
      Remove the specified end note if present.
      Parameters:
      pos - Array position of the end note to be removed.
      Returns:
      True if the end note was removed.
      Since:
      4.0.0