Package org.apache.poi.ooxml

Class POIXMLDocumentPart

    • 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,
                          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​(PackagePart part)
        Creates an POIXMLDocumentPart representing the given package part and relationship. Called by read(POIXMLFactory, 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, Map)

      • POIXMLDocumentPart

        public POIXMLDocumentPart​(POIXMLDocumentPart parent,
                          PackagePart part)
        Creates an POIXMLDocumentPart representing the given package part, relationship and parent Called by read(POIXMLFactory, 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, Map)

    • Method Detail

      • isCommitted

        public boolean isCommitted()
        to check whether embedded part is already committed
        Returns:
        return true if embedded part is committed
        Since:
        4.1.2

      • 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
        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 List<POIXMLDocumentPart> getRelations()
        Returns the list of child relations for this POIXMLDocumentPart
        Returns:
        child relations

      • getRelationParts

        public final List<POIXMLDocumentPart.RelationPart> getRelationParts()
        Returns the list of child relations for this POIXMLDocumentPart
        Returns:
        child relations

      • addRelation

        public final POIXMLDocumentPart.RelationPart addRelation​(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​(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(POIXMLDocumentPart) 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.

      • commit

        protected void commit()
               throws 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();
   try (OutputStream out = part.getOutputStream()) {
     XmlObject bean = getXmlBean(); //the "model" which holds changes in memory
     bean.save(out, DEFAULT_XML_OPTIONS);
   }
 }
        Throws:
        IOException - a subclass may throw an IOException if the changes can't be committed

      • onSave

        protected final void onSave​(Set<PackagePart> alreadySaved)
                     throws IOException
        Save changes in the underlying OOXML package. Recursively fires commit() for each package part
        Parameters:
        alreadySaved - context set containing already visited nodes
        Throws:
        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

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

      • onDocumentCreate

        protected void onDocumentCreate()
                         throws IOException
        Fired when a new package part is created
        Throws:
        IOException - a subclass may throw an IOException on document creation

      • onDocumentRead

        protected void onDocumentRead()
                       throws IOException
        Fired when a package part is read
        Throws:
        IOException - a subclass may throw an IOException when a document is read

      • onDocumentRemove

        protected void onDocumentRemove()
                         throws IOException
        Fired when a package part is about to be removed from the package
        Throws:
        IOException - a subclass may throw an IOException when a document is removed