org.apache.poi
Class POIXMLDocumentPart

java.lang.Object
  extended by 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.

Author:
Yegor Kozlov

Nested Class Summary
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
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
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.


POIXMLDocumentPart

public POIXMLDocumentPart(OPCPackage pkg,
                          java.lang.String coreDocumentRel)
Construct POIXMLDocumentPart representing a custom "core document" package part.


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

Throws:
InvalidFormatException

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


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.

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

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

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

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

onDocumentCreate

protected void onDocumentCreate()
                         throws java.io.IOException
Fired when a new package part is created

Throws:
java.io.IOException

onDocumentRead

protected void onDocumentRead()
                       throws java.io.IOException
Fired when a package part is read

Throws:
java.io.IOException

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

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

Throws:
java.io.IOException


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