org.apache.poi.ooxml

## Class POIXMLDocumentPart

- java.lang.Object
- - org.apache.poi.ooxml.POIXMLDocumentPart

- Direct Known Subclasses:
    CalculationChain, CommentsTable, ExternalLinksTable, MapInfo, POIXMLDocument, SharedStringsTable, SingleXmlCells, StylesTable, ThemesTable, XDDFChart, XDGFXMLDocumentPart, XSLFCommentAuthors, XSLFComments, XSLFFontData, XSLFObjectData, XSLFPictureData, XSLFSheet, XSLFTableStyles, XSLFTheme, XSSFDrawing, XSSFPictureData, XSSFPivotCache, XSSFPivotCacheDefinition, XSSFPivotCacheRecords, XSSFPivotTable, XSSFSheet, XSSFTable, XSSFVBAPart, XSSFVMLDrawing, XWPFAbstractFootnotesEndnotes, XWPFHeaderFooter, XWPFNumbering, XWPFPictureData, XWPFSettings, XWPFStyles

      public class POIXMLDocumentPart
      extends java.lang.Object

  Represents an entry of a OOXML package.

  Each POIXMLDocumentPart keeps a reference to the underlying a `PackagePart`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `POIXMLDocumentPart.RelationPart` The RelationPart is a cached relationship between the document, which contains the RelationPart, and one of its referenced child document parts.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `POIXMLDocumentPart()` Creates new POIXMLDocumentPart - called by client code to create new parts from scratch.
    `POIXMLDocumentPart(OPCPackage pkg)` Construct POIXMLDocumentPart representing a "core document" package part.
    `POIXMLDocumentPart(OPCPackage pkg, java.lang.String coreDocumentRel)` Construct POIXMLDocumentPart representing a custom "core document" package part.
    `POIXMLDocumentPart(PackagePart part)` Creates an POIXMLDocumentPart representing the given package part and relationship.
    `POIXMLDocumentPart(POIXMLDocumentPart parent, PackagePart part)` Creates an POIXMLDocumentPart representing the given package part, relationship and parent Called by `read(POIXMLFactory, java.util.Map)` when reading in an existing file.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `_invokeOnDocumentRead(POIXMLDocumentPart part)` Deprecated.
    `POIXMLDocumentPart.RelationPart` | `addRelation(java.lang.String relId, POIXMLRelation relationshipType, POIXMLDocumentPart part)` Add a new child POIXMLDocumentPart
    `protected void` | `commit()` Save the content in the underlying package part.
    `POIXMLDocumentPart` | `createRelationship(POIXMLRelation descriptor, POIXMLFactory factory)` Create a new child POIXMLDocumentPart
    `POIXMLDocumentPart` | `createRelationship(POIXMLRelation descriptor, POIXMLFactory factory, int idx)` Create a new child POIXMLDocumentPart
    `POIXMLDocumentPart.RelationPart` | `createRelationship(POIXMLRelation descriptor, POIXMLFactory factory, int idx, boolean noRelation)` Create a new child POIXMLDocumentPart
    `protected int` | `getNextPartNumber(POIXMLRelation descriptor, int minIdx)` Identifies the next available part number for a part of the given type, if possible, otherwise -1 if none are available.
    `PackagePart` | `getPackagePart()` Provides access to the underlying PackagePart
    `POIXMLDocumentPart` | `getParent()` Returns the parent POIXMLDocumentPart.
    `POIXMLDocumentPart` | `getRelationById(java.lang.String id)` Returns the target `POIXMLDocumentPart`, where a `PackageRelationship` is set from the `PackagePart` of this `POIXMLDocumentPart` to the `PackagePart` of the target `POIXMLDocumentPart` with a `PackageRelationship.getId()` matching the given parameter value.
    `java.lang.String` | `getRelationId(POIXMLDocumentPart part)` Returns the first `PackageRelationship.getId()` of the `PackageRelationship`, that sources from the `PackagePart` of this `POIXMLDocumentPart` to the `PackagePart` of the given parameter value.
    `POIXMLDocumentPart.RelationPart` | `getRelationPartById(java.lang.String id)` Returns the target `POIXMLDocumentPart.RelationPart`, where a `PackageRelationship` is set from the `PackagePart` of this `POIXMLDocumentPart` to the `PackagePart` of the target `POIXMLDocumentPart` with a `PackageRelationship.getId()` matching the given parameter value.
    `java.util.List<POIXMLDocumentPart.RelationPart>` | `getRelationParts()` Returns the list of child relations for this POIXMLDocumentPart
    `java.util.List<POIXMLDocumentPart>` | `getRelations()` Returns the list of child relations for this POIXMLDocumentPart
    `protected PackagePart` | `getTargetPart(PackageRelationship rel)` Get the PackagePart that is the target of a relationship from this Part.
    `boolean` | `isCommited()` Deprecated. use @link{#isCommitted()}
    `boolean` | `isCommitted()` to check whether embedded part is already committed
    `protected void` | `onDocumentCreate()` Fired when a new package part is created
    `protected void` | `onDocumentRead()` Fired when a package part is read
    `protected void` | `onDocumentRemove()` Fired when a package part is about to be removed from the package
    `protected void` | `onSave(java.util.Set<PackagePart> alreadySaved)` Save changes in the underlying OOXML package.
    `protected void` | `prepareForCommit()` Ensure that a memory based package part does not have lingering data from previous commit() calls.
    `protected void` | `read(POIXMLFactory factory, java.util.Map<PackagePart,POIXMLDocumentPart> context)` Iterate through the underlying PackagePart and create child POIXMLFactory instances using the specified factory
    `protected void` | `rebase(OPCPackage pkg)` When you open something like a theme, call this to re-base the XML Document onto the core child of the current core document
    `protected void` | `removeRelation(POIXMLDocumentPart part)` Remove the relation to the specified part in this package and remove the part, if it is no longer needed.
    `protected boolean` | `removeRelation(POIXMLDocumentPart part, boolean removeUnusedParts)` Remove the relation to the specified part in this package and remove the part, if it is no longer needed and flag is set to true.
    `protected void` | `removeRelation(java.lang.String partId)` Remove the relation to the specified part in this package and remove the part, if it is no longer needed.
    `void` | `setCommited(boolean isCommitted)` Deprecated. use @link{#setCommitted(isCommitted)}
    `void` | `setCommitted(boolean isCommitted)` setter method to set embedded part is committed
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### POIXMLDocumentPart

          public POIXMLDocumentPart(OPCPackage pkg)

      Construct POIXMLDocumentPart representing a "core document" package part.
      Parameters:
        `pkg` - the OPCPackage containing this document

    - #### POIXMLDocumentPart

          public POIXMLDocumentPart(OPCPackage pkg,
                                    java.lang.String coreDocumentRel)

      Construct POIXMLDocumentPart representing a custom "core document" package part.
      Parameters:
        `pkg` - the OPCPackage containing this document
        `coreDocumentRel` - the relation type of this document

    - #### POIXMLDocumentPart

          public POIXMLDocumentPart()

      Creates new POIXMLDocumentPart - called by client code to create new parts from scratch.
      See Also:
        `createRelationship(POIXMLRelation, POIXMLFactory, int, boolean)`

    - #### POIXMLDocumentPart

          public POIXMLDocumentPart(PackagePart part)

      Creates an POIXMLDocumentPart representing the given package part and relationship. Called by `read(POIXMLFactory, java.util.Map)` when reading in an existing file.
      Parameters:
        `part` - - The package part that holds xml data representing this sheet.
      Since:
        POI 3.14-Beta1
      See Also:
        `read(POIXMLFactory, java.util.Map)`

    - #### POIXMLDocumentPart

          public POIXMLDocumentPart(POIXMLDocumentPart parent,
                                    PackagePart part)

      Creates an POIXMLDocumentPart representing the given package part, relationship and parent Called by `read(POIXMLFactory, java.util.Map)` when reading in an existing file.
      Parameters:
        `parent` - - Parent part
        `part` - - The package part that holds xml data representing this sheet.
      Since:
        POI 3.14-Beta1
      See Also:
        `read(POIXMLFactory, java.util.Map)`

  - ### Method Detail

    - #### isCommited

          @Removal(version="5.0.0")
           @Deprecated
          public boolean isCommited()

      Deprecated. use @link{#isCommitted()}
      to check whether embedded part is already committed
      Returns:
        return true if embedded part is committed

    - #### isCommitted

          public boolean isCommitted()

      to check whether embedded part is already committed
      Returns:
        return true if embedded part is committed
      Since:
        4.1.2

    - #### setCommited

          @Removal(version="5.0.0")
           @Deprecated
          public void setCommited(boolean isCommitted)

      Deprecated. use @link{#setCommitted(isCommitted)}
      setter method to set embedded part is committed
      Parameters:
        `isCommitted` - boolean value

    - #### setCommitted

          public void setCommitted(boolean isCommitted)

      setter method to set embedded part is committed
      Parameters:
        `isCommitted` - boolean value

    - #### rebase

          protected final void rebase(OPCPackage pkg)
                               throws InvalidFormatException

      When you open something like a theme, call this to re-base the XML Document onto the core child of the current core document
      Parameters:
        `pkg` - the package to be rebased
      Throws:
        `InvalidFormatException` - if there was an error in the core document relation
        `java.lang.IllegalStateException` - if there are more than one core document relations

    - #### getPackagePart

          public final PackagePart getPackagePart()

      Provides access to the underlying PackagePart
      Returns:
        the underlying PackagePart

    - #### getRelations

          public final java.util.List<POIXMLDocumentPart> getRelations()

      Returns the list of child relations for this POIXMLDocumentPart
      Returns:
        child relations

    - #### getRelationParts

          public final java.util.List<POIXMLDocumentPart.RelationPart> getRelationParts()

      Returns the list of child relations for this POIXMLDocumentPart
      Returns:
        child relations

    - #### getRelationById

          public final POIXMLDocumentPart getRelationById(java.lang.String id)

      Returns the target `POIXMLDocumentPart`, where a `PackageRelationship` is set from the `PackagePart` of this `POIXMLDocumentPart` to the `PackagePart` of the target `POIXMLDocumentPart` with a `PackageRelationship.getId()` matching the given parameter value.
      Parameters:
        `id` - The relation id to look for
      Returns:
        the target part of the relation, or null, if none exists

    - #### getRelationPartById

          public final POIXMLDocumentPart.RelationPart getRelationPartById(java.lang.String id)

      Returns the target `POIXMLDocumentPart.RelationPart`, where a `PackageRelationship` is set from the `PackagePart` of this `POIXMLDocumentPart` to the `PackagePart` of the target `POIXMLDocumentPart` with a `PackageRelationship.getId()` matching the given parameter value.
      Parameters:
        `id` - The relation id to look for
      Returns:
        the target relation part, or null, if none exists
      Since:
        4.0.0

    - #### getRelationId

          public final java.lang.String getRelationId(POIXMLDocumentPart part)

      Returns the first `PackageRelationship.getId()` of the `PackageRelationship`, that sources from the `PackagePart` of this `POIXMLDocumentPart` to the `PackagePart` of the given parameter value.

      There can be multiple references to the given `POIXMLDocumentPart` and only the first in the order of creation is returned.

      Parameters:
        `part` - The `POIXMLDocumentPart` for which the according relation-id shall be found.
      Returns:
        The value of the `PackageRelationship.getId()` or null, if parts are not related.

    - #### addRelation

          public final POIXMLDocumentPart.RelationPart addRelation(java.lang.String relId,
                                                                   POIXMLRelation relationshipType,
                                                                   POIXMLDocumentPart part)

      Add a new child POIXMLDocumentPart
      Parameters:
        `relId` - the preferred relation id, when null the next free relation id will be used
        `relationshipType` - the package relationship type
        `part` - the child to add
      Returns:
        the new RelationPart
      Since:
        3.14-Beta1

    - #### removeRelation

          protected final void removeRelation(POIXMLDocumentPart part)

      Remove the relation to the specified part in this package and remove the part, if it is no longer needed.

      If there are multiple relationships to the same part, this will only remove the first relationship in the order of creation. The removal via the part id (`removeRelation(String)` is preferred.

      Parameters:
        `part` - the part which relation is to be removed from this document

    - #### removeRelation

          protected final boolean removeRelation(POIXMLDocumentPart part,
                                                 boolean removeUnusedParts)

      Remove the relation to the specified part in this package and remove the part, if it is no longer needed and flag is set to true.

      If there are multiple relationships to the same part, this will only remove the first relationship in the order of creation. The removal via the part id (`removeRelation(String, boolean)` is preferred.

      Parameters:
        `part` - The related part, to which the relation shall be removed.
        `removeUnusedParts` - true, if the part shall be removed from the package if not needed any longer.
      Returns:
        true, if the relation was removed

    - #### removeRelation

          protected final void removeRelation(java.lang.String partId)

      Remove the relation to the specified part in this package and remove the part, if it is no longer needed.

      If there are multiple relationships to the same part, this will only remove the first relationship in the order of creation. The removal via the part id (`removeRelation(String)` is preferred.

      Parameters:
        `partId` - the part id which relation is to be removed from this document
      Since:
        4.0.0

    - #### getParent

          public final POIXMLDocumentPart getParent()

      Returns the parent POIXMLDocumentPart. All parts except root have not-null parent.
      Returns:
        the parent POIXMLDocumentPart or `null` for the root element.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### commit

          protected void commit()
                         throws java.io.IOException

      Save the content in the underlying package part. Default implementation is empty meaning that the package part is left unmodified.

      Sub-classes should override and add logic to marshal the "model" into Ooxml4J.

      For example, the code saving a generic XML entry may look as follows:

           protected void commit() throws IOException {
             PackagePart part = getPackagePart();
             OutputStream out = part.getOutputStream();
             XmlObject bean = getXmlBean(); //the "model" which holds changes in memory
             bean.save(out, DEFAULT_XML_OPTIONS);
             out.close();
           }

      Throws:
        `java.io.IOException` - a subclass may throw an IOException if the changes can't be committed

    - #### onSave

          protected final void onSave(java.util.Set<PackagePart> alreadySaved)
                               throws java.io.IOException

      Save changes in the underlying OOXML package. Recursively fires `commit()` for each package part
      Parameters:
        `alreadySaved` - context set containing already visited nodes
      Throws:
        `java.io.IOException` - a related part may throw an IOException if the changes can't be saved

    - #### prepareForCommit

          protected void prepareForCommit()

      Ensure that a memory based package part does not have lingering data from previous commit() calls.

      Note: This is overwritten for some objects, as *PictureData seem to store the actual content in the part directly without keeping a copy like all others therefore we need to handle them differently.

    - #### createRelationship

          public final POIXMLDocumentPart createRelationship(POIXMLRelation descriptor,
                                                             POIXMLFactory factory)

      Create a new child POIXMLDocumentPart
      Parameters:
        `descriptor` - the part descriptor
        `factory` - the factory that will create an instance of the requested relation
      Returns:
        the created child POIXMLDocumentPart
      Throws:
        `PartAlreadyExistsException` - If rule M1.12 is not verified : Packages shall not contain equivalent part names and package implementers shall neither create nor recognize packages with equivalent part names.

    - #### createRelationship

          public final POIXMLDocumentPart createRelationship(POIXMLRelation descriptor,
                                                             POIXMLFactory factory,
                                                             int idx)

      Create a new child POIXMLDocumentPart
      Parameters:
        `descriptor` - the part descriptor
        `factory` - the factory that will create an instance of the requested relation
        `idx` - part number
      Returns:
        the created child POIXMLDocumentPart
      Throws:
        `PartAlreadyExistsException` - If rule M1.12 is not verified : Packages shall not contain equivalent part names and package implementers shall neither create nor recognize packages with equivalent part names.

    - #### getNextPartNumber

          protected final int getNextPartNumber(POIXMLRelation descriptor,
                                                int minIdx)

      Identifies the next available part number for a part of the given type, if possible, otherwise -1 if none are available. The found (valid) index can then be safely given to `createRelationship(POIXMLRelation, POIXMLFactory, int)` or `createRelationship(POIXMLRelation, POIXMLFactory, int, boolean)` without naming clashes. If parts with other types are already claiming a name for this relationship type (eg a `XSSFRelation.CHART` using the drawing part namespace normally used by `XSSFRelation.DRAWINGS`), those will be considered when finding the next spare number.
      Parameters:
        `descriptor` - The relationship type to find the part number for
        `minIdx` - The minimum free index to assign, use -1 for any
      Returns:
        The next free part number, or -1 if none available

    - #### createRelationship

          public final POIXMLDocumentPart.RelationPart createRelationship(POIXMLRelation descriptor,
                                                                          POIXMLFactory factory,
                                                                          int idx,
                                                                          boolean noRelation)

      Create a new child POIXMLDocumentPart
      Parameters:
        `descriptor` - the part descriptor
        `factory` - the factory that will create an instance of the requested relation
        `idx` - part number
        `noRelation` - if true, then no relationship is added.
      Returns:
        the created child POIXMLDocumentPart
      Throws:
        `PartAlreadyExistsException` - If rule M1.12 is not verified : Packages shall not contain equivalent part names and package implementers shall neither create nor recognize packages with equivalent part names.

    - #### read

          protected void read(POIXMLFactory factory,
                              java.util.Map<PackagePart,POIXMLDocumentPart> context)
                       throws OpenXML4JException

      Iterate through the underlying PackagePart and create child POIXMLFactory instances using the specified factory
      Parameters:
        `factory` - the factory object that creates POIXMLFactory instances
        `context` - context map containing already visited noted keyed by targetURI
      Throws:
        `OpenXML4JException` - thrown when a related part can't be read

    - #### getTargetPart

          protected PackagePart getTargetPart(PackageRelationship rel)
                                       throws InvalidFormatException

      Get the PackagePart that is the target of a relationship from this Part.
      Parameters:
        `rel` - The relationship
      Returns:
        The target part
      Throws:
        `InvalidFormatException` - thrown if the related part has is erroneous

    - #### onDocumentCreate

          protected void onDocumentCreate()
                                   throws java.io.IOException

      Fired when a new package part is created
      Throws:
        `java.io.IOException` - a subclass may throw an IOException on document creation

    - #### onDocumentRead

          protected void onDocumentRead()
                                 throws java.io.IOException

      Fired when a package part is read
      Throws:
        `java.io.IOException` - a subclass may throw an IOException when a document is read

    - #### onDocumentRemove

          protected void onDocumentRemove()
                                   throws java.io.IOException

      Fired when a package part is about to be removed from the package
      Throws:
        `java.io.IOException` - a subclass may throw an IOException when a document is removed

    - #### _invokeOnDocumentRead

          @Internal
           @Deprecated
          public static void _invokeOnDocumentRead(POIXMLDocumentPart part)
                                                                   throws java.io.IOException

      Deprecated.
      Internal method, do not use!

      This method only exists to allow access to protected `onDocumentRead()` from `XWPFDocument` without reflection. It should be removed.

      Parameters:
        `part` - the part which is to be read
      Throws:
        `java.io.IOException` - if the part can't be read

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.