org.apache.poi.openxml4j.opc
Class OPCPackage

java.lang.Object
  extended by org.apache.poi.openxml4j.opc.OPCPackage
All Implemented Interfaces:
java.io.Closeable, RelationshipSource
Direct Known Subclasses:
Package

public abstract class OPCPackage
extends java.lang.Object
implements RelationshipSource, java.io.Closeable

Represents a container that can store multiple data objects.

Version:
0.1
Author:
Julien Chable, CDubet

Field Summary
protected  ContentTypeManager contentTypeManager
          Manage parts content types of this package.
protected static PackageAccess defaultPackageAccess
          Default package access.
protected  PartMarshaller defaultPartMarshaller
          Default part marshaller.
protected  boolean isDirty
          Flag if a modification is done to the document.
protected  java.lang.String originalPackagePath
          File path of this package.
protected  java.io.OutputStream output
          Output stream for writing this package.
protected  PackagePropertiesPart packageProperties
          Core package properties.
protected  PackagePartCollection partList
          Package parts collection.
protected  java.util.Hashtable<ContentType,PartMarshaller> partMarshallers
          Part marshallers by content type.
protected  java.util.Hashtable<ContentType,PartUnmarshaller> partUnmarshallers
          Part unmarshallers by content type.
protected  PackageRelationshipCollection relationships
          Package relationships.
 
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).
 void addMarshaller(java.lang.String contentType, PartMarshaller marshaller)
          Add a marshaller.
protected  PackagePart addPackagePart(PackagePart part)
          Add the specified part to the package.
 PackageRelationship addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType)
          Add a package relationship.
 PackageRelationship addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType, java.lang.String relID)
          Add a relationship to the package (except relationships part).
 void addThumbnail(java.lang.String path)
          Add a thumbnail to the package.
 void addUnmarshaller(java.lang.String contentType, PartUnmarshaller unmarshaller)
          Add an unmarshaller.
 void clearRelationships()
          Clear package relationships.
 void close()
          Close the open, writable package and save its content.
protected abstract  void closeImpl()
          Close the package and cause a save of the package.
 boolean containPart(PackagePartName partName)
          Check if a part already exists in this package from its name.
static OPCPackage create(java.io.File file)
          Creates a new package.
static OPCPackage create(java.io.OutputStream output)
           
static OPCPackage create(java.lang.String path)
          Creates a new package.
 PackagePart createPart(PackagePartName partName, java.lang.String contentType)
          Create and add a part, with the specified name and content type, to the package.
 PackagePart createPart(PackagePartName partName, java.lang.String contentType, java.io.ByteArrayOutputStream content)
          Add a part to the package.
protected abstract  PackagePart createPartImpl(PackagePartName partName, java.lang.String contentType, boolean loadRelationships)
          Core method to create a package part.
 void deletePart(PackagePartName partName)
          Delete the part with the specified name and its associated relationships part if one exists.
 void deletePartRecursive(PackagePartName partName)
          Delete the part with the specified name and all part listed in its associated relationships part if one exists.
 void ensureRelationships()
          Ensure that the relationships collection is not null.
 void flush()
          Flush the package : save all.
protected abstract  void flushImpl()
          Flush the package but not save.
 PackageAccess getPackageAccess()
          Get the package access mode.
 PackageProperties getPackageProperties()
          Retrieves or creates if none exists, core package property part.
 PackagePart getPart(PackagePartName partName)
          Retrieve a part identified by its name.
 PackagePart getPart(PackageRelationship partRel)
          Get the target part from the specified relationship.
protected abstract  PackagePart getPartImpl(PackagePartName partName)
          Get the package part mapped to the specified URI.
 java.util.ArrayList<PackagePart> getParts()
          Load the parts of the archive if it has not been done yet.
 java.util.ArrayList<PackagePart> getPartsByContentType(java.lang.String contentType)
          Retrieve parts by content type.
 java.util.List<PackagePart> getPartsByName(java.util.regex.Pattern namePattern)
           
 java.util.ArrayList<PackagePart> getPartsByRelationshipType(java.lang.String relationshipType)
          Retrieve parts by relationship type.
protected abstract  PackagePart[] getPartsImpl()
          Get all parts link to the package.
 PackageRelationship getRelationship(java.lang.String id)
          Retrieves a package relationship from its id.
 PackageRelationshipCollection getRelationships()
          Retrieves all package relationships.
 PackageRelationshipCollection getRelationshipsByType(java.lang.String relationshipType)
          Retrieves all relationships with the specified type.
 boolean hasRelationships()
          Knows if the part have any relationships.
 boolean isRelationshipExists(PackageRelationship rel)
          Checks if the specified relationship is part of this package part.
static OPCPackage open(java.io.InputStream in)
          Open a package.
static OPCPackage open(java.lang.String path)
          Open a package with read/write permission.
static OPCPackage open(java.lang.String path, PackageAccess access)
          Open a package.
static OPCPackage openOrCreate(java.io.File file)
          Opens a package if it exists, else it creates one.
 void removeMarshaller(java.lang.String contentType)
          Remove a marshaller by its content type.
 void removePart(PackagePart part)
          Remove the specified part in this package.
 void removePart(PackagePartName partName)
          Remove a part in this package.
protected abstract  void removePartImpl(PackagePartName partName)
          Core method to delete a package part.
 void removePartRecursive(PackagePartName partName)
          Remove a part from this package as well as its relationship part, if one exists, and all parts listed in the relationship part.
 void removeRelationship(java.lang.String id)
          Delete a relationship from this package.
 void removeUnmarshaller(java.lang.String contentType)
          Remove an unmarshaller by its content type.
 boolean replaceContentType(java.lang.String oldContentType, java.lang.String newContentType)
          Replace a content type in this package.
 void revert()
          Close the package WITHOUT saving its content.
protected abstract  void revertImpl()
          Close the package without saving the document.
 void save(java.io.File targetFile)
          Save the document in the specified file.
 void save(java.io.OutputStream outputStream)
          Save the document in the specified output stream.
protected abstract  void saveImpl(java.io.OutputStream outputStream)
          Save the package into the specified output stream.
 boolean validatePackage(OPCPackage pkg)
          Validates the package compliance with the OPC specifications.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

defaultPackageAccess

protected static final PackageAccess defaultPackageAccess
Default package access.


partList

protected PackagePartCollection partList
Package parts collection.


relationships

protected PackageRelationshipCollection relationships
Package relationships.


partMarshallers

protected java.util.Hashtable<ContentType,PartMarshaller> partMarshallers
Part marshallers by content type.


defaultPartMarshaller

protected PartMarshaller defaultPartMarshaller
Default part marshaller.


partUnmarshallers

protected java.util.Hashtable<ContentType,PartUnmarshaller> partUnmarshallers
Part unmarshallers by content type.


packageProperties

protected PackagePropertiesPart packageProperties
Core package properties.


contentTypeManager

protected ContentTypeManager contentTypeManager
Manage parts content types of this package.


isDirty

protected boolean isDirty
Flag if a modification is done to the document.


originalPackagePath

protected java.lang.String originalPackagePath
File path of this package.


output

protected java.io.OutputStream output
Output stream for writing this package.

Method Detail

open

public static OPCPackage open(java.lang.String path)
                       throws InvalidFormatException
Open a package with read/write permission.

Parameters:
path - The document path.
Returns:
A Package object, else null.
Throws:
InvalidFormatException - If the specified file doesn't exist, and a parsing error occur.

open

public static OPCPackage open(java.lang.String path,
                              PackageAccess access)
                       throws InvalidFormatException
Open a package.

Parameters:
path - The document path.
access - PackageBase access.
Returns:
A PackageBase object, else null.
Throws:
InvalidFormatException - If the specified file doesn't exist, and a parsing error occur.

open

public static OPCPackage open(java.io.InputStream in)
                       throws InvalidFormatException,
                              java.io.IOException
Open a package. Note - uses quite a bit more memory than open(String), which doesn't need to hold the whole zip file in memory, and can take advantage of native methods

Parameters:
in - The InputStream to read the package from
Returns:
A PackageBase object
Throws:
InvalidFormatException
java.io.IOException

openOrCreate

public static OPCPackage openOrCreate(java.io.File file)
                               throws InvalidFormatException
Opens a package if it exists, else it creates one.

Parameters:
file - The file to open or to create.
Returns:
A newly created package if the specified file does not exist, else the package extract from the file.
Throws:
InvalidFormatException - Throws if the specified file exist and is not valid.

create

public static OPCPackage create(java.lang.String path)
Creates a new package.

Parameters:
path - Path of the document.
Returns:
A newly created PackageBase ready to use.

create

public static OPCPackage create(java.io.File file)
Creates a new package.

Parameters:
file - Path of the document.
Returns:
A newly created PackageBase ready to use.

create

public static OPCPackage create(java.io.OutputStream output)

flush

public void flush()
Flush the package : save all.

See Also:
close()

close

public void close()
           throws java.io.IOException
Close the open, writable package and save its content. If your package is open read only, then you should call revert() when finished with the package.

Specified by:
close in interface java.io.Closeable
Throws:
java.io.IOException - If an IO exception occur during the saving process.

revert

public void revert()
Close the package WITHOUT saving its content. Reinitialize this package and cancel all changes done to it.


addThumbnail

public void addThumbnail(java.lang.String path)
                  throws java.io.IOException
Add a thumbnail to the package. This method is provided to make easier the addition of a thumbnail in a package. You can do the same work by using the traditionnal relationship and part mechanism.

Parameters:
path - The full path to the image file.
Throws:
java.io.IOException

getPackageProperties

public PackageProperties getPackageProperties()
                                       throws InvalidFormatException
Retrieves or creates if none exists, core package property part.

Returns:
The PackageProperties part of this package.
Throws:
InvalidFormatException

getPart

public PackagePart getPart(PackagePartName partName)
Retrieve a part identified by its name.

Parameters:
partName - Part name of the part to retrieve.
Returns:
The part with the specified name, else null.

getPartsByContentType

public java.util.ArrayList<PackagePart> getPartsByContentType(java.lang.String contentType)
Retrieve parts by content type.

Parameters:
contentType - The content type criteria.
Returns:
All part associated to the specified content type.

getPartsByRelationshipType

public java.util.ArrayList<PackagePart> getPartsByRelationshipType(java.lang.String relationshipType)
Retrieve parts by relationship type.

Parameters:
relationshipType - Relationship type.
Returns:
All parts which are the target of a relationship with the specified type, if the method can't retrieve relationships from the package, then return null.

getPartsByName

public java.util.List<PackagePart> getPartsByName(java.util.regex.Pattern namePattern)

getPart

public PackagePart getPart(PackageRelationship partRel)
Get the target part from the specified relationship.

Parameters:
partRel - The part relationship uses to retrieve the part.

getParts

public java.util.ArrayList<PackagePart> getParts()
                                          throws InvalidFormatException
Load the parts of the archive if it has not been done yet. The relationships of each part are not loaded. Note - Rule M4.1 states that there may only ever be one Core Properties Part, but Office produced files will sometimes have multiple! As Office ignores all but the first, we relax Compliance with Rule M4.1, and ignore all others silently too.

Returns:
All this package's parts.
Throws:
InvalidFormatException

createPart

public PackagePart createPart(PackagePartName partName,
                              java.lang.String contentType)
Create and add a part, with the specified name and content type, to the package.

Parameters:
partName - Part name.
contentType - Part content type.
Returns:
The newly created part.
Throws:
InvalidFormatException - 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.
See Also:
createPartImpl(PackagePartName, String, boolean)

createPart

public PackagePart createPart(PackagePartName partName,
                              java.lang.String contentType,
                              java.io.ByteArrayOutputStream content)
Add a part to the package.

Parameters:
partName - Part name of the part to create.
contentType - type associated with the file
content - the contents to add. In order to have faster operation in document merge, the data are stored in memory not on a hard disk
Returns:
The new part.
See Also:
createPart(PackagePartName, String)

addPackagePart

protected PackagePart addPackagePart(PackagePart part)
Add the specified part to the package. If a part already exists in the package with the same name as the one specified, then we replace the old part by the specified part.

Parameters:
part - The part to add (or replace).
Returns:
The part added to the package, the same as the one specified.
Throws:
InvalidFormatException - 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.

removePart

public void removePart(PackagePart part)
Remove the specified part in this package. If this part is relationship part, then delete all relationships in the source part.

Parameters:
part - The part to remove. If null, skip the action.
See Also:
removePart(PackagePartName)

removePart

public void removePart(PackagePartName partName)
Remove a part in this package. If this part is relationship part, then delete all relationships in the source part.

Parameters:
partName - The part name of the part to remove.

removePartRecursive

public void removePartRecursive(PackagePartName partName)
                         throws InvalidFormatException
Remove a part from this package as well as its relationship part, if one exists, and all parts listed in the relationship part. Be aware that this do not delete relationships which target the specified part.

Parameters:
partName - The name of the part to delete.
Throws:
InvalidFormatException - Throws if the associated relationship part of the specified part is not valid.

deletePart

public void deletePart(PackagePartName partName)
Delete the part with the specified name and its associated relationships part if one exists. Prefer the use of this method to delete a part in the package, compare to the remove() methods that don't remove associated relationships part.

Parameters:
partName - Name of the part to delete

deletePartRecursive

public void deletePartRecursive(PackagePartName partName)
Delete the part with the specified name and all part listed in its associated relationships part if one exists. This process is recursively apply to all parts in the relationships part of the specified part. Prefer the use of this method to delete a part in the package, compare to the remove() methods that don't remove associated relationships part.

Parameters:
partName - Name of the part to delete

containPart

public boolean containPart(PackagePartName partName)
Check if a part already exists in this package from its name.

Parameters:
partName - Part name to check.
Returns:
true if the part is logically added to this package, else false.

addRelationship

public PackageRelationship addRelationship(PackagePartName targetPartName,
                                           TargetMode targetMode,
                                           java.lang.String relationshipType,
                                           java.lang.String relID)
Add a relationship to the package (except relationships part). Check rule M4.1 : The format designer shall specify and the format producer shall create at most one core properties relationship for a package. A format consumer shall consider more than one core properties relationship for a package to be an error. If present, the relationship shall target the Core Properties 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 - Target part name.
targetMode - Target mode, either Internal or External.
relationshipType - Relationship type.
relID - ID of the relationship.
Returns:
The newly created and added relationship
See Also:
PackageRelationshipTypes

addRelationship

public PackageRelationship addRelationship(PackagePartName targetPartName,
                                           TargetMode targetMode,
                                           java.lang.String relationshipType)
Add a package relationship.

Specified by:
addRelationship in interface RelationshipSource
Parameters:
targetPartName - Target part name.
targetMode - Target mode, either Internal or External.
relationshipType - Relationship type.
Returns:
The newly created and added relationship
See Also:
PackageRelationshipTypes

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)

removeRelationship

public void removeRelationship(java.lang.String id)
Delete a relationship from this package.

Specified by:
removeRelationship in interface RelationshipSource
Parameters:
id - Id of the relationship to delete.

getRelationships

public PackageRelationshipCollection getRelationships()
Retrieves all package relationships.

Specified by:
getRelationships in interface RelationshipSource
Returns:
All package relationships of this package.
Throws:
OpenXML4JException
See Also:
getRelationshipsHelper(String)

getRelationshipsByType

public PackageRelationshipCollection getRelationshipsByType(java.lang.String relationshipType)
Retrieves all relationships with the specified type.

Specified by:
getRelationshipsByType in interface RelationshipSource
Parameters:
relationshipType - The filter specifying the relationship type.
Returns:
All relationships with the specified relationship type.

clearRelationships

public void clearRelationships()
Clear package relationships.

Specified by:
clearRelationships in interface RelationshipSource

ensureRelationships

public void ensureRelationships()
Ensure that the relationships collection is not null.


getRelationship

public PackageRelationship getRelationship(java.lang.String id)
Description copied from interface: RelationshipSource
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)

hasRelationships

public boolean hasRelationships()
Description copied from interface: RelationshipSource
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)
Description copied from interface: RelationshipSource
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)

addMarshaller

public void addMarshaller(java.lang.String contentType,
                          PartMarshaller marshaller)
Add a marshaller.

Parameters:
contentType - The content type to bind to the specified marshaller.
marshaller - The marshaller to register with the specified content type.

addUnmarshaller

public void addUnmarshaller(java.lang.String contentType,
                            PartUnmarshaller unmarshaller)
Add an unmarshaller.

Parameters:
contentType - The content type to bind to the specified unmarshaller.
unmarshaller - The unmarshaller to register with the specified content type.

removeMarshaller

public void removeMarshaller(java.lang.String contentType)
Remove a marshaller by its content type.

Parameters:
contentType - The content type associated with the marshaller to remove.

removeUnmarshaller

public void removeUnmarshaller(java.lang.String contentType)
Remove an unmarshaller by its content type.

Parameters:
contentType - The content type associated with the unmarshaller to remove.

getPackageAccess

public PackageAccess getPackageAccess()
Get the package access mode.

Returns:
the packageAccess The current package access.

validatePackage

public boolean validatePackage(OPCPackage pkg)
                        throws InvalidFormatException
Validates the package compliance with the OPC specifications.

Returns:
true if the package is valid else false
Throws:
InvalidFormatException

save

public void save(java.io.File targetFile)
          throws java.io.IOException
Save the document in the specified file.

Parameters:
targetFile - Destination file.
Throws:
java.io.IOException - Throws if an IO exception occur.
See Also:
save(OutputStream)

save

public void save(java.io.OutputStream outputStream)
          throws java.io.IOException
Save the document in the specified output stream.

Parameters:
outputStream - The stream to save the package.
Throws:
java.io.IOException
See Also:
saveImpl(OutputStream)

createPartImpl

protected abstract PackagePart createPartImpl(PackagePartName partName,
                                              java.lang.String contentType,
                                              boolean loadRelationships)
Core method to create a package part. This method must be implemented by the subclass.

Parameters:
partName - URI of the part to create.
contentType - Content type of the part to create.
Returns:
The newly created package part.

removePartImpl

protected abstract void removePartImpl(PackagePartName partName)
Core method to delete a package part. This method must be implemented by the subclass.

Parameters:
partName - The URI of the part to delete.

flushImpl

protected abstract void flushImpl()
Flush the package but not save.


closeImpl

protected abstract void closeImpl()
                           throws java.io.IOException
Close the package and cause a save of the package.

Throws:
java.io.IOException

revertImpl

protected abstract void revertImpl()
Close the package without saving the document. Discard all changes made to this package.


saveImpl

protected abstract void saveImpl(java.io.OutputStream outputStream)
                          throws java.io.IOException
Save the package into the specified output stream.

Parameters:
outputStream - The output stream use to save this package.
Throws:
java.io.IOException

getPartImpl

protected abstract PackagePart getPartImpl(PackagePartName partName)
Get the package part mapped to the specified URI.

Parameters:
partName - The URI of the part to retrieve.
Returns:
The package part located by the specified URI, else null.

getPartsImpl

protected abstract PackagePart[] getPartsImpl()
                                       throws InvalidFormatException
Get all parts link to the package.

Returns:
A list of the part owned by the package.
Throws:
InvalidFormatException

replaceContentType

public boolean replaceContentType(java.lang.String oldContentType,
                                  java.lang.String newContentType)
Replace a content type in this package.

A typical scneario to call this method is to rename a template file to the main format, e.g. ".dotx" to ".docx" ".dotm" to ".docm" ".xltx" to ".xlsx" ".xltm" to ".xlsm" ".potx" to ".pptx" ".potm" to ".pptm"

For example, a code converting a .xlsm macro workbook to .xlsx would look as follows:



     OPCPackage pkg = OPCPackage.open(new FileInputStream("macro-workbook.xlsm"));
     pkg.replaceContentType(
         "application/vnd.ms-excel.sheet.macroEnabled.main+xml",
         "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml");

     FileOutputStream out = new FileOutputStream("workbook.xlsx");
     pkg.save(out);
     out.close();

    

Parameters:
oldContentType - the content type to be replaced
newContentType - the replacement
Returns:
whether replacement was succesfull
Since:
POI-3.8


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