org.apache.poi.openxml4j.opc

## Class PackagePart

- java.lang.Object
- - org.apache.poi.openxml4j.opc.PackagePart

- All Implemented Interfaces:
    java.lang.Comparable<PackagePart>, RelationshipSource
  Direct Known Subclasses:
    MemoryPackagePart, PackagePropertiesPart, ZipPackagePart

      public abstract class PackagePart
      extends java.lang.Object
      implements RelationshipSource, java.lang.Comparable<PackagePart>

  Provides a base class for parts stored in a Package.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected OPCPackage` | `_container` This part's container.
    `protected ContentType` | `_contentType` The type of content of this part.
    `protected PackagePartName` | `_partName` The part name.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `PackagePart(OPCPackage pack, PackagePartName partName, ContentType contentType)` Constructor.
    `protected` | `PackagePart(OPCPackage pack, PackagePartName partName, ContentType contentType, boolean loadRelationships)` Constructor.
    `` | `PackagePart(OPCPackage pack, PackagePartName partName, java.lang.String contentType)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `PackageRelationship` | `addExternalRelationship(java.lang.String target, java.lang.String relationshipType)` Adds an external relationship to a part (except relationships part).
    `PackageRelationship` | `addExternalRelationship(java.lang.String target, java.lang.String relationshipType, java.lang.String id)` Adds an external relationship to a part (except relationships part).
    `PackageRelationship` | `addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType)` Add a relationship to a part (except relationships part).
    `PackageRelationship` | `addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType, java.lang.String id)` Add a relationship to a part (except relationships part).
    `PackageRelationship` | `addRelationship(java.net.URI targetURI, TargetMode targetMode, java.lang.String relationshipType)` Add a relationship to a part (except relationships part).
    `PackageRelationship` | `addRelationship(java.net.URI targetURI, TargetMode targetMode, java.lang.String relationshipType, java.lang.String id)` Add a relationship to a part (except relationships part).
    `void` | `clear()` Allows sub-classes to clean up before new data is added.
    `void` | `clearRelationships()` Delete all the relationships attached to this.
    `abstract void` | `close()` Close this part : flush this part, close the input stream and output stream.
    `int` | `compareTo(PackagePart other)` Compare based on the package part name, using a natural sort order
    `PackageRelationship` | `findExistingRelation(PackagePart packagePart)` Check if the new part was already added before via PackagePart.addRelationship()
    `abstract void` | `flush()` Flush the content of this part.
    `java.lang.String` | `getContentType()`
    `ContentType` | `getContentTypeDetails()`
    `java.io.InputStream` | `getInputStream()` Get the input stream of this part to read its content.
    `protected abstract java.io.InputStream` | `getInputStreamImpl()` Method that gets the input stream for this part.
    `java.io.OutputStream` | `getOutputStream()` Get the output stream of this part.
    `protected abstract java.io.OutputStream` | `getOutputStreamImpl()` Method that gets the output stream for this part.
    `OPCPackage` | `getPackage()`
    `PackagePartName` | `getPartName()`
    `PackagePart` | `getRelatedPart(PackageRelationship rel)` Get the PackagePart that is the target of a relationship.
    `PackageRelationship` | `getRelationship(java.lang.String id)` Retrieves a package relationship from its id.
    `PackageRelationshipCollection` | `getRelationships()` Retrieve all the relationships attached to this part.
    `PackageRelationshipCollection` | `getRelationshipsByType(java.lang.String relationshipType)` Retrieve all relationships attached to this part which have the specified type.
    `long` | `getSize()`
    `boolean` | `hasRelationships()` Knows if the part have any relationships.
    `boolean` | `isDeleted()`
    `boolean` | `isRelationshipExists(PackageRelationship rel)` Checks if the specified relationship is part of this package part.
    `boolean` | `isRelationshipPart()`
    `abstract boolean` | `load(java.io.InputStream ios)` Load the content of this part.
    `void` | `removeRelationship(java.lang.String id)` Delete the relationship specified by its id.
    `abstract boolean` | `save(java.io.OutputStream zos)` Save the content of this part and the associated relationships part (if this part own at least one relationship) into the specified output stream.
    `void` | `setContentType(java.lang.String contentType)` Set the content type.
    `void` | `setDeleted(boolean isDeleted)`
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### _container

          protected OPCPackage _container

      This part's container.

    - #### _partName

          protected PackagePartName _partName

      The part name. (required by the specification [M1.1])

    - #### _contentType

          protected ContentType _contentType

      The type of content of this part. (required by the specification [M1.2])

  - ### Constructor Detail

    - #### PackagePart

          protected PackagePart(OPCPackage pack,
                                PackagePartName partName,
                                ContentType contentType)
                         throws InvalidFormatException

      Constructor.
      Parameters:
        `pack` - Parent package.
        `partName` - The part name, relative to the parent Package root.
        `contentType` - The content type.
      Throws:
        `InvalidFormatException` - If the specified URI is not valid.

    - #### PackagePart

          protected PackagePart(OPCPackage pack,
                                PackagePartName partName,
                                ContentType contentType,
                                boolean loadRelationships)
                         throws InvalidFormatException

      Constructor.
      Parameters:
        `pack` - Parent package.
        `partName` - The part name, relative to the parent Package root.
        `contentType` - The content type.
        `loadRelationships` - Specify if the relationships will be loaded
      Throws:
        `InvalidFormatException` - If the specified URI is not valid.

    - #### PackagePart

          public PackagePart(OPCPackage pack,
                             PackagePartName partName,
                             java.lang.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 Detail

    - #### 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(java.lang.String target,
                                                             java.lang.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
      See Also:
        `RelationshipSource.addExternalRelationship(java.lang.String, java.lang.String)`

    - #### addExternalRelationship

          public PackageRelationship addExternalRelationship(java.lang.String target,
                                                             java.lang.String relationshipType,
                                                             java.lang.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:
        `RelationshipSource.addExternalRelationship(java.lang.String, java.lang.String)`

    - #### addRelationship

          public PackageRelationship addRelationship(PackagePartName targetPartName,
                                                     TargetMode targetMode,
                                                     java.lang.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
      See Also:
        `RelationshipSource.addRelationship(org.apache.poi.openxml4j.opc.PackagePartName, org.apache.poi.openxml4j.opc.TargetMode, java.lang.String)`

    - #### addRelationship

          public PackageRelationship addRelationship(PackagePartName targetPartName,
                                                     TargetMode targetMode,
                                                     java.lang.String relationshipType,
                                                     java.lang.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.
        `java.lang.IllegalArgumentException` - if targetPartName, targetMode or relationshipType are passed as null
      See Also:
        `RelationshipSource.addRelationship(org.apache.poi.openxml4j.opc.PackagePartName, org.apache.poi.openxml4j.opc.TargetMode, java.lang.String, java.lang.String)`

    - #### addRelationship

          public PackageRelationship addRelationship(java.net.URI targetURI,
                                                     TargetMode targetMode,
                                                     java.lang.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:
        `RelationshipSource.addRelationship(org.apache.poi.openxml4j.opc.PackagePartName, org.apache.poi.openxml4j.opc.TargetMode, java.lang.String)`

    - #### addRelationship

          public PackageRelationship addRelationship(java.net.URI targetURI,
                                                     TargetMode targetMode,
                                                     java.lang.String relationshipType,
                                                     java.lang.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:
        `RelationshipSource.addRelationship(org.apache.poi.openxml4j.opc.PackagePartName, org.apache.poi.openxml4j.opc.TargetMode, java.lang.String, java.lang.String)`

    - #### clearRelationships

          public void clearRelationships()

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

    - #### removeRelationship

          public void removeRelationship(java.lang.String id)

      Delete the relationship specified by its id.
      Specified by:
        `removeRelationship` in interface `RelationshipSource`
      Parameters:
        `id` - The ID identified the part to delete.
      See Also:
        `RelationshipSource.removeRelationship(java.lang.String)`

    - #### 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`
      See Also:
        `RelationshipSource.getRelationships()`

    - #### getRelationship

          public PackageRelationship getRelationship(java.lang.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
      See Also:
        `RelationshipSource.getRelationship(java.lang.String)`

    - #### getRelationshipsByType

          public PackageRelationshipCollection getRelationshipsByType(java.lang.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.
      See Also:
        `RelationshipSource.getRelationshipsByType(java.lang.String)`

    - #### 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.
      See Also:
        `RelationshipSource.hasRelationships()`

    - #### 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
      See Also:
        `RelationshipSource.isRelationshipExists(org.apache.poi.openxml4j.opc.PackageRelationship)`

    - #### 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 java.io.InputStream getInputStream()
                                             throws java.io.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:
        `java.io.IOException` - If creating the input-stream fails.

    - #### getOutputStream

          public java.io.OutputStream getOutputStream()

      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
      See Also:
        `MemoryPackagePart`

    - #### getPartName

          public PackagePartName getPartName()

      Returns:
        the uri

    - #### getContentType

          public java.lang.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(java.lang.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 java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### compareTo

          public int compareTo(PackagePart other)

      Compare based on the package part name, using a natural sort order
      Specified by:
        `compareTo` in interface `java.lang.Comparable<PackagePart>`

    - #### getInputStreamImpl

          protected abstract java.io.InputStream getInputStreamImpl()
                                                             throws java.io.IOException

      Method that gets the input stream for this part.
      Returns:
        input stream for this part
      Throws:
        `java.io.IOException` - Throws if an IO Exception occur in the implementation method.

    - #### getOutputStreamImpl

          protected abstract java.io.OutputStream getOutputStreamImpl()

      Method that gets the output stream for this part.
      Returns:
        output stream for this part

    - #### save

          public abstract boolean save(java.io.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:
        boolean flag that shows if the save succeeded
      Throws:
        `OpenXML4JException` - If any exception occur.

    - #### load

          public abstract boolean load(java.io.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, else false.
      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.

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