Package org.apache.poi.xwpf.usermodel

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.

    • Constructor Detail

      • XWPFDocument

        public XWPFDocument​(OPCPackage pkg)
             throws IOException
        Parameters:
        pkg - OPC package
        Throws:
        IOException - If reading data from the package fails
        POIXMLException - a RuntimeException that can be caused by invalid OOXML data
        RuntimeException - a number of other runtime exceptions can be thrown, especially if there are problems with the input format

      • XWPFDocument

        public XWPFDocument​(InputStream is)
             throws IOException
        Parameters:
        is - The InputStream to read data from
        Throws:
        IOException - If reading data from the stream fails
        POIXMLException - a RuntimeException that can be caused by invalid OOXML data
        RuntimeException - a number of other runtime exceptions can be thrown, especially if there are problems with the input format

      • XWPFDocument

        public XWPFDocument()

    • Method Detail

      • newPackage

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

      • getDocument

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

      • getBodyElementsSpliterator

        public Spliterator<IBodyElement> getBodyElementsSpliterator()
        returns a Spliterator with paragraphs and tables
        Since:
        POI 5.2.0

      • 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

      • 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

      • 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

      • 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)

      • getFootnoteByID

        public XWPFFootnote getFootnoteByID​(int id)

      • getEndnoteByID

        public XWPFEndnote getEndnoteByID​(int id)

      • getDocComments

        public XWPFComments getDocComments()
        Get Comments
        Returns:
        comments

      • 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.

      • 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​(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​(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

      • createParagraph

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

      • createComments

        public XWPFComments createComments()
        Creates an empty comments for the document if one does not already exist
        Returns:
        comments

      • 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
        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

      • 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

      • createTOC

        public void createTOC()

      • setTable

        public void setTable​(int pos,
                     XWPFTable table)
        Replace content of table in array tables at position pos with a

      • 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
        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

      • 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

      • getSettings

        public XWPFSettings getSettings()
        Returns:
        document level settings
        Since:
        POI 5.2.1

      • getPictureDataByID

        public XWPFPictureData getPictureDataByID​(String blipID)
        returns the PictureData by 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)
        Description copied from interface: IBody
        Returns the paragraph corresponding to the provided CTP.
        Specified by:
        getParagraph in interface IBody
        Parameters:
        p - is instance of CTP and is searching for an XWPFParagraph
        Returns:
        The paragraph corresponding to the CTP, or null if there is no corresponding paragraph in this body.

      • 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
        Returns:
        a table by its CTTbl-Object or null

      • 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

      • 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

      • 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

      • 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

      • 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