org.apache.poi.openxml4j.opc
Class PackagePart

java.lang.Object
  extended by org.apache.poi.openxml4j.opc.PackagePart
All Implemented Interfaces:
RelationshipSource
Direct Known Subclasses:
DigitalCertificatePart, MemoryPackagePart, PackageDigitalSignature, PackagePropertiesPart, ZipPackagePart

public abstract class PackagePart
extends java.lang.Object
implements RelationshipSource

Provides a base class for parts stored in a Package.

Version:
0.9
Author:
Julien Chable

Field Summary
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
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
 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 clearRelationships()
          Delete all the relationships attached to this.
abstract  void close()
          Close this part : flush this part, close the input stream and output stream.
abstract  void flush()
          Flush the content of this part.
 java.lang.String getContentType()
           
 java.io.InputStream getInputStream()
          Get the input stream of this part to read its content.
protected abstract  java.io.InputStream getInputStreamImpl()
          Abtract method that get the input stream of this part.
 java.io.OutputStream getOutputStream()
          Get the output stream of this part.
protected abstract  java.io.OutputStream getOutputStreamImpl()
          Abstract method that get the output stream of 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.
 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
Method Detail

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:
InvalidFormatException - 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)

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:
InvalidFormatException - 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:
OpenXML4JException
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

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

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 intot a MemoryPackagePart in order to write inside (the standard Java API doesn't allow to write in the file)

See Also:
MemoryPackagePart

getPartName

public PackagePartName getPartName()
Returns:
the uri

getContentType

public java.lang.String getContentType()
Returns:
the contentType

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

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getInputStreamImpl

protected abstract java.io.InputStream getInputStreamImpl()
                                                   throws java.io.IOException
Abtract method that get the input stream of this part.

Throws:
java.io.IOException - Throws if an IO Exception occur in the implementation method.

getOutputStreamImpl

protected abstract java.io.OutputStream getOutputStreamImpl()
Abstract method that get the output stream of 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.
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.



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