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
,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 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 Description POIXMLDocumentPart()
Creates new POIXMLDocumentPart - called by client code to create new parts from scratch.POIXMLDocumentPart(POIXMLDocumentPart parent, PackagePart part)
Creates an POIXMLDocumentPart representing the given package part, relationship and parent Called byread(POIXMLFactory, java.util.Map)
when reading in an existing file.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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static void
_invokeOnDocumentRead(POIXMLDocumentPart part)
Deprecated.POIXMLDocumentPart.RelationPart
addRelation(java.lang.String relId, POIXMLRelation relationshipType, POIXMLDocumentPart part)
Add a new child POIXMLDocumentPartprotected void
commit()
Save the content in the underlying package part.POIXMLDocumentPart
createRelationship(POIXMLRelation descriptor, POIXMLFactory factory)
Create a new child POIXMLDocumentPartPOIXMLDocumentPart
createRelationship(POIXMLRelation descriptor, POIXMLFactory factory, int idx)
Create a new child POIXMLDocumentPartPOIXMLDocumentPart.RelationPart
createRelationship(POIXMLRelation descriptor, POIXMLFactory factory, int idx, boolean noRelation)
Create a new child POIXMLDocumentPartprotected 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 PackagePartPOIXMLDocumentPart
getParent()
Returns the parent POIXMLDocumentPart.POIXMLDocumentPart
getRelationById(java.lang.String id)
Returns the targetPOIXMLDocumentPart
, where aPackageRelationship
is set from thePackagePart
of thisPOIXMLDocumentPart
to thePackagePart
of the targetPOIXMLDocumentPart
with aPackageRelationship.getId()
matching the given parameter value.java.lang.String
getRelationId(POIXMLDocumentPart part)
Returns the firstPackageRelationship.getId()
of thePackageRelationship
, that sources from thePackagePart
of thisPOIXMLDocumentPart
to thePackagePart
of the given parameter value.POIXMLDocumentPart.RelationPart
getRelationPartById(java.lang.String id)
Returns the targetPOIXMLDocumentPart.RelationPart
, where aPackageRelationship
is set from thePackagePart
of thisPOIXMLDocumentPart
to thePackagePart
of the targetPOIXMLDocumentPart
with aPackageRelationship.getId()
matching the given parameter value.java.util.List<POIXMLDocumentPart.RelationPart>
getRelationParts()
Returns the list of child relations for this POIXMLDocumentPartjava.util.List<POIXMLDocumentPart>
getRelations()
Returns the list of child relations for this POIXMLDocumentPartprotected PackagePart
getTargetPart(PackageRelationship rel)
Get the PackagePart that is the target of a relationship from this Part.boolean
isCommited()
to check whether embedded part is already committedprotected void
onDocumentCreate()
Fired when a new package part is createdprotected void
onDocumentRead()
Fired when a package part is readprotected void
onDocumentRemove()
Fired when a package part is about to be removed from the packageprotected 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 factoryprotected 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 documentprotected 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.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.void
setCommited(boolean isCommited)
setter method to set embedded part is committedjava.lang.String
toString()
-
-
-
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 documentcoreDocumentRel
- the relation type of this document
-
POIXMLDocumentPart
public POIXMLDocumentPart()
Creates new POIXMLDocumentPart - called by client code to create new parts from scratch.
-
POIXMLDocumentPart
public POIXMLDocumentPart(PackagePart part)
Creates an POIXMLDocumentPart representing the given package part and relationship. Called byread(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 byread(POIXMLFactory, java.util.Map)
when reading in an existing file.- Parameters:
parent
- - Parent partpart
- - 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
public boolean isCommited()
to check whether embedded part is already committed- Returns:
- return true if embedded part is committed
-
setCommited
public void setCommited(boolean isCommited)
setter method to set embedded part is committed- Parameters:
isCommited
- 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 relationjava.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 targetPOIXMLDocumentPart
, where aPackageRelationship
is set from thePackagePart
of thisPOIXMLDocumentPart
to thePackagePart
of the targetPOIXMLDocumentPart
with aPackageRelationship.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 targetPOIXMLDocumentPart.RelationPart
, where aPackageRelationship
is set from thePackagePart
of thisPOIXMLDocumentPart
to thePackagePart
of the targetPOIXMLDocumentPart
with aPackageRelationship.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 firstPackageRelationship.getId()
of thePackageRelationship
, that sources from thePackagePart
of thisPOIXMLDocumentPart
to thePackagePart
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
- ThePOIXMLDocumentPart
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 usedrelationshipType
- the package relationship typepart
- 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 classjava.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 firescommit()
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 descriptorfactory
- 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 descriptorfactory
- the factory that will create an instance of the requested relationidx
- 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 tocreateRelationship(POIXMLRelation, POIXMLFactory, int)
orcreateRelationship(POIXMLRelation, POIXMLFactory, int, boolean)
without naming clashes. If parts with other types are already claiming a name for this relationship type (eg aXSSFRelation.CHART
using the drawing part namespace normally used byXSSFRelation.DRAWINGS
), those will be considered when finding the next spare number.- Parameters:
descriptor
- The relationship type to find the part number forminIdx
- 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 descriptorfactory
- the factory that will create an instance of the requested relationidx
- part numbernoRelation
- 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 instancescontext
- 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()
fromXWPFDocument
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
-
-