POIXMLDocumentPart (POI API Documentation)

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

Direct Known Subclasses:

CalculationChain, CommentsTable, ExternalLinksTable, MapInfo, POIXMLDocument, SharedStringsTable, SingleXmlCells, StylesTable, ThemesTable, XDGFXMLDocumentPart, XSLFChart, XSLFCommentAuthors, XSLFComments, XSLFPictureData, XSLFSheet, XSLFTableStyles, XSLFTheme, XSSFChart, XSSFDrawing, XSSFPictureData, XSSFPivotCache, XSSFPivotCacheDefinition, XSSFPivotCacheRecords, XSSFPivotTable, XSSFSheet, XSSFTable, XSSFVBAPart, XSSFVMLDrawing, XWPFFootnotes, 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(PackagePart part, PackageRelationship rel)` Deprecated. in POI 3.14, scheduled for removal in POI 3.16
`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.
`POIXMLDocumentPart(POIXMLDocumentPart parent, PackagePart part, PackageRelationship rel)` Deprecated. in POI 3.14, scheduled for removal in POI 3.16

Method Summary

Methods
Modifier and Type	Method and Description
`static void`	`_invokeOnDocumentRead(POIXMLDocumentPart part)` Deprecated.
`void`	`addRelation(java.lang.String id, POIXMLDocumentPart part)` Deprecated. in POI 3.14, scheduled for removal in POI 3.16
`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
`protected POIXMLDocumentPart.RelationPart`	`createRelationship(POIXMLRelation descriptor, POIXMLFactory factory, int idx, boolean noRelation)` Create a new child POIXMLDocumentPart
`PackagePart`	`getPackagePart()` Provides access to the underlying PackagePart
`PackageRelationship`	`getPackageRelationship()` Deprecated. in POI 3.14, scheduled for removal in POI 3.16
`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 `PackageRelationship.getId()` of the `PackageRelationship`, that sources from the `PackagePart` of this `POIXMLDocumentPart` to the `PackagePart` of 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.
`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.
`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)
  - POIXMLDocumentPart
```
@Deprecated
public POIXMLDocumentPart(PackagePart part,
                             PackageRelationship rel)
```
    Deprecated. in POI 3.14, scheduled for removal in POI 3.16
    
    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.
    rel - - the relationship of the given package part
    See Also:
    read(POIXMLFactory, java.util.Map)
  - POIXMLDocumentPart
```
@Deprecated
public POIXMLDocumentPart(POIXMLDocumentPart parent,
                             PackagePart part,
                             PackageRelationship rel)
```
    Deprecated. in POI 3.14, scheduled for removal in POI 3.16
    
    Creates an POIXMLDocumentPart representing the given package part, relationship and parent Called by read(POIXMLFactory, java.util.Map) when reading in an exisiting file.
    
    Parameters:
    parent - - Parent part
    part - - The package part that holds xml data represenring this sheet.
    rel - - the relationship of the given package part
    See Also:
    read(POIXMLFactory, java.util.Map)
- Method Detail
  - 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
  - getPackageRelationship
```
@Deprecated
public final PackageRelationship getPackageRelationship()
```
    Deprecated. in POI 3.14, scheduled for removal in POI 3.16
    
    Provides access to the PackageRelationship that identifies this POIXMLDocumentPart
    
    Returns:
    the PackageRelationship that identifies this POIXMLDocumentPart
  - 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
  - getRelationId
```
public final java.lang.String getRelationId(POIXMLDocumentPart part)
```
    Returns the PackageRelationship.getId() of the PackageRelationship, that sources from the PackagePart of this POIXMLDocumentPart to the PackagePart of the given parameter value.
    
    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
```
@Deprecated
public final void addRelation(java.lang.String id,
                          POIXMLDocumentPart part)
```
    Deprecated. in POI 3.14, scheduled for removal in POI 3.16
    
    Add a new child POIXMLDocumentPart
    
    Parameters:
    id - the id of an existing child to replace
    part - the child to add
  - 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.
    
    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.
    
    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
  - 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.
  - createRelationship
```
protected 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

Class POIXMLDocumentPart

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

POIXMLDocumentPart

POIXMLDocumentPart

POIXMLDocumentPart

POIXMLDocumentPart

POIXMLDocumentPart

POIXMLDocumentPart

POIXMLDocumentPart

Method Detail

rebase

getPackagePart

getPackageRelationship

getRelations

getRelationParts

getRelationById

getRelationId

addRelation

addRelation

removeRelation

removeRelation

getParent

toString

commit

onSave

prepareForCommit

createRelationship

createRelationship

createRelationship

read

getTargetPart

onDocumentCreate

onDocumentRead

onDocumentRemove

_invokeOnDocumentRead