Package org.apache.poi.openxml4j.opc

Class PackagePart

java.lang.Object
org.apache.poi.openxml4j.opc.PackagePart
All Implemented Interfaces:
Comparable<PackagePart>, RelationshipSource
Direct Known Subclasses:
EncryptedTempFilePackagePart, MemoryPackagePart, PackagePropertiesPart, TempFilePackagePart, ZipPackagePart
public abstract class PackagePart extends Object implements RelationshipSource, Comparable<PackagePart>
Provides a base class for parts stored in a Package.

  • Constructor Details

    • PackagePart

      public PackagePart(OPCPackage pack, PackagePartName partName, String contentType) throws InvalidFormatException
      Constructor.
      Parameters:
      pack - Parent package.
      partName - The part name, relative to the parent Package root.
      contentType - The Multipurpose Internet Mail Extensions (MIME) content type of the part's data stream.
      Throws:
      InvalidFormatException - If the specified URI is not valid.

  • Method Details

    • findExistingRelation

      public PackageRelationship findExistingRelation(PackagePart packagePart)
      Check if the new part was already added before via PackagePart.addRelationship()
      Parameters:
      packagePart - to find the relationship for
      Returns:
      The existing relationship, or null if there isn't yet one

    • addExternalRelationship

      public PackageRelationship addExternalRelationship(String target, String relationshipType)
      Adds an external relationship to a part (except relationships part). The targets of external relationships are not subject to the same validity checks that internal ones are, as the contents is potentially any file, URL or similar.
      Specified by:
      addExternalRelationship in interface RelationshipSource
      Parameters:
      target - External target of the relationship
      relationshipType - Type of relationship.
      Returns:
      The newly created and added relationship

    • addExternalRelationship

      public PackageRelationship addExternalRelationship(String target, String relationshipType, String id)
      Adds an external relationship to a part (except relationships part). The targets of external relationships are not subject to the same validity checks that internal ones are, as the contents is potentially any file, URL or similar.
      Specified by:
      addExternalRelationship in interface RelationshipSource
      Parameters:
      target - External target of the relationship
      relationshipType - Type of relationship.
      id - Relationship unique id.
      Returns:
      The newly created and added relationship
      See Also:

    • addRelationship

      public PackageRelationship addRelationship(PackagePartName targetPartName, TargetMode targetMode, String relationshipType)
      Add a relationship to a part (except relationships part).
      Specified by:
      addRelationship in interface RelationshipSource
      Parameters:
      targetPartName - Name of the target part. This one must be relative to the source root directory of the part.
      targetMode - Mode [Internal|External].
      relationshipType - Type of relationship.
      Returns:
      The newly created and added relationship

    • addRelationship

      public PackageRelationship addRelationship(PackagePartName targetPartName, TargetMode targetMode, String relationshipType, String id)
      Add a relationship to a part (except relationships part).

      Check rule M1.25: The Relationships part shall not have relationships to any other part. Package implementers shall enforce this requirement upon the attempt to create such a relationship and shall treat any such relationship as invalid.

      Specified by:
      addRelationship in interface RelationshipSource
      Parameters:
      targetPartName - Name of the target part. This one must be relative to the source root directory of the part.
      targetMode - Mode [Internal|External].
      relationshipType - Type of relationship.
      id - Relationship unique id.
      Returns:
      The newly created and added relationship
      Throws:
      InvalidOperationException - If a writing operation is done on a read only package or invalid nested relations are created.
      IllegalArgumentException - if targetPartName, targetMode or relationshipType are passed as null

    • addRelationship

      public PackageRelationship addRelationship(URI targetURI, TargetMode targetMode, String relationshipType)
      Add a relationship to a part (except relationships part).
      Parameters:
      targetURI - URI the target part. Must be relative to the source root directory of the part.
      targetMode - Mode [Internal|External].
      relationshipType - Type of relationship.
      Returns:
      The newly created and added relationship
      See Also:

    • addRelationship

      public PackageRelationship addRelationship(URI targetURI, TargetMode targetMode, String relationshipType, String id)
      Add a relationship to a part (except relationships part).

      Check rule M1.25: The Relationships part shall not have relationships to any other part. Package implementers shall enforce this requirement upon the attempt to create such a relationship and shall treat any such relationship as invalid.

      Parameters:
      targetURI - URI of the target part. Must be relative to the source root directory of the part.
      targetMode - Mode [Internal|External].
      relationshipType - Type of relationship.
      id - Relationship unique id.
      Returns:
      The newly created and added relationship
      Throws:
      InvalidOperationException - If the URI point to a relationship part URI.
      See Also:

    • clearRelationships

      public void clearRelationships()
      Description copied from interface: RelationshipSource
      Delete all the relationships attached to this.
      Specified by:
      clearRelationships in interface RelationshipSource

    • removeRelationship

      public void removeRelationship(String id)
      Delete the relationship specified by its id.
      Specified by:
      removeRelationship in interface RelationshipSource
      Parameters:
      id - The ID identified the part to delete.

    • getRelationships

      public PackageRelationshipCollection getRelationships() throws InvalidFormatException
      Retrieve all the relationships attached to this part.
      Specified by:
      getRelationships in interface RelationshipSource
      Returns:
      This part's relationships.
      Throws:
      InvalidOperationException - Throws if the package is open en write only mode.
      InvalidFormatException

    • getRelationship

      public PackageRelationship getRelationship(String id)
      Retrieves a package relationship from its id.
      Specified by:
      getRelationship in interface RelationshipSource
      Parameters:
      id - ID of the package relationship to retrieve.
      Returns:
      The package relationship

    • getRelationshipsByType

      public PackageRelationshipCollection getRelationshipsByType(String relationshipType) throws InvalidFormatException
      Retrieve all relationships attached to this part which have the specified type.
      Specified by:
      getRelationshipsByType in interface RelationshipSource
      Parameters:
      relationshipType - Relationship type filter.
      Returns:
      All relationships from this part that have the specified type.
      Throws:
      InvalidFormatException - If an error occurs while parsing the part.
      InvalidOperationException - If the package is open in write only mode.

    • hasRelationships

      public boolean hasRelationships()
      Knows if the part have any relationships.
      Specified by:
      hasRelationships in interface RelationshipSource
      Returns:
      true if the part have at least one relationship else false.

    • isRelationshipExists

      public boolean isRelationshipExists(PackageRelationship rel)
      Checks if the specified relationship is part of this package part.
      Specified by:
      isRelationshipExists in interface RelationshipSource
      Parameters:
      rel - The relationship to check.
      Returns:
      true if the specified relationship exists in this part, else returns false

    • getRelatedPart

      public PackagePart getRelatedPart(PackageRelationship rel) throws InvalidFormatException
      Get the PackagePart that is the target of a relationship.
      Parameters:
      rel - A relationship from this part to another one
      Returns:
      The target part of the relationship
      Throws:
      InvalidFormatException - If the specified URI is not valid.

    • getInputStream

      public InputStream getInputStream() throws IOException
      Get the input stream of this part to read its content.
      Returns:
      The input stream of the content of this part, else null.
      Throws:
      IOException - If creating the input-stream fails.

    • getOutputStream

      public OutputStream getOutputStream() throws IOException
      Get the output stream of this part. If the part is originally embedded in Zip package, it'll be transform into a MemoryPackagePart in order to write inside (the standard Java API doesn't allow to write in the file)
      Returns:
      output stream for this part
      Throws:
      IOException
      See Also:

    • getPartName

      public PackagePartName getPartName()
      Returns:
      the uri

    • getContentType

      public String getContentType()
      Returns:
      The Content Type of the part

    • getContentTypeDetails

      public ContentType getContentTypeDetails()
      Returns:
      The Content Type, including parameters, of the part

    • setContentType

      public void setContentType(String contentType) throws InvalidFormatException
      Set the content type.
      Parameters:
      contentType - the contentType to set
      Throws:
      InvalidFormatException - Throws if the content type is not valid.
      InvalidOperationException - Throws if you try to change the content type whereas this part is already attached to a package.

    • getPackage

      public OPCPackage getPackage()

    • isRelationshipPart

      public boolean isRelationshipPart()
      Returns:
      true if this part is a relationship

    • isDeleted

      public boolean isDeleted()
      Returns:
      true if this part has been logically deleted

    • setDeleted

      public void setDeleted(boolean isDeleted)
      Parameters:
      isDeleted - the isDeleted to set

    • getSize

      public long getSize()
      Returns:
      The length of the part in bytes, or -1 if not known

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • compareTo

      public int compareTo(PackagePart other)
      Compare based on the package part name, using a natural sort order
      Specified by:
      compareTo in interface Comparable<PackagePart>

    • save

      public abstract boolean save(OutputStream zos) throws OpenXML4JException
      Save the content of this part and the associated relationships part (if this part own at least one relationship) into the specified output stream.
      Parameters:
      zos - Output stream to save this part.
      Returns:
      true if the content has been successfully stored, false otherwise. More information about errors may be logged via Log4j 2.
      Throws:
      OpenXML4JException - If any exception occur.

    • load

      public abstract boolean load(InputStream ios) throws InvalidFormatException
      Load the content of this part.
      Parameters:
      ios - The input stream of the content to load.
      Returns:
      true if the content has been successfully loaded, false otherwise. More information about errors may be logged via Log4j 2.
      Throws:
      InvalidFormatException - Throws if the content format is invalid.

    • close

      public abstract void close()
      Close this part : flush this part, close the input stream and output stream. After this method call, the part must be available for packaging.

    • flush

      public abstract void flush()
      Flush the content of this part. If the input stream and/or output stream as in a waiting state to read or write, the must to empty their respective buffer.

    • clear

      public void clear()
      Allows sub-classes to clean up before new data is added.