public abstract class OPCPackage extends java.lang.Object implements RelationshipSource, java.io.Closeable
Modifier and Type | Field and Description |
---|---|
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 java.util.Map<ContentType,PartMarshaller> |
partMarshallers
Part marshallers by content type.
|
protected java.util.Map<ContentType,PartUnmarshaller> |
partUnmarshallers
Part unmarshallers by content type.
|
protected PackageRelationshipCollection |
relationships
Package relationships.
|
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).
|
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 |
addThumbnail(java.lang.String filename,
java.io.InputStream data)
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.
|
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)
Retrieve parts by name
|
java.util.ArrayList<PackagePart> |
getPartsByRelationshipType(java.lang.String relationshipType)
Retrieve parts by relationship type.
|
protected abstract PackagePartCollection |
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.
|
int |
getUnusedPartIndex(java.lang.String nameTemplate)
Get an unused part index based on the namePattern, which doesn't exist yet
and has the lowest positive index
|
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.File file)
Open a package with read/write permission.
|
static OPCPackage |
open(java.io.File file,
PackageAccess access)
Open a package.
|
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 |
open(ZipEntrySource zipEntry)
Open an user provided
ZipEntrySource with read-only permission. |
static OPCPackage |
openOrCreate(java.io.File file)
Opens a package if it exists, else it creates one.
|
void |
registerPartAndContentType(PackagePart part)
Add the specified part, and register its content type with the content
type manager.
|
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.
|
void |
unregisterPartAndContentType(PackagePartName partName)
Remove the specified part, and clear its content type from the content
type manager.
|
boolean |
validatePackage(OPCPackage pkg)
Validates the package compliance with the OPC specifications.
|
protected static final PackageAccess defaultPackageAccess
protected PackageRelationshipCollection relationships
protected final java.util.Map<ContentType,PartMarshaller> partMarshallers
protected final PartMarshaller defaultPartMarshaller
protected final java.util.Map<ContentType,PartUnmarshaller> partUnmarshallers
protected PackagePropertiesPart packageProperties
protected ContentTypeManager contentTypeManager
protected boolean isDirty
protected java.lang.String originalPackagePath
protected java.io.OutputStream output
public static OPCPackage open(java.lang.String path) throws InvalidFormatException
path
- The document path.InvalidFormatException
- If the specified file doesn't exist, and a parsing error
occur.public static OPCPackage open(java.io.File file) throws InvalidFormatException
file
- The file to open.InvalidFormatException
- If the specified file doesn't exist, and a parsing error
occur.public static OPCPackage open(ZipEntrySource zipEntry) throws InvalidFormatException
ZipEntrySource
with read-only permission.
This method can be used to stream data into POI.
Opposed to other open variants, the data is read as-is, e.g. there aren't
any zip-bomb protection put in place.zipEntry
- the custom sourceInvalidFormatException
- if a parsing error occur.public static OPCPackage open(java.lang.String path, PackageAccess access) throws InvalidFormatException, InvalidOperationException
path
- The document path.access
- PackageBase access.InvalidFormatException
- If the specified file doesn't exist, and a parsing error
occur.InvalidOperationException
- If the zip file cannot be opened.InvalidFormatException
- if the package is not valid.public static OPCPackage open(java.io.File file, PackageAccess access) throws InvalidFormatException
file
- The file to open.access
- PackageBase access.InvalidFormatException
- If the specified file doesn't exist, and a parsing error
occur.public static OPCPackage open(java.io.InputStream in) throws InvalidFormatException, java.io.IOException
open(String)
, which
doesn't need to hold the whole zip file in memory, and can take advantage
of native methodsin
- The InputStream to read the package fromInvalidFormatException
- Throws if the specified file exist and is not valid.java.io.IOException
- If reading the stream failspublic static OPCPackage openOrCreate(java.io.File file) throws InvalidFormatException
file
- The file to open or to create.InvalidFormatException
- Throws if the specified file exist and is not valid.public static OPCPackage create(java.lang.String path)
path
- Path of the document.public static OPCPackage create(java.io.File file)
file
- Path of the document.public static OPCPackage create(java.io.OutputStream output)
public void flush()
close()
public void close() throws java.io.IOException
revert()
when finished with the package.
This method is not thread-safe.close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
java.io.IOException
- If an IO exception occur during the saving process.public void revert()
public void addThumbnail(java.lang.String path) throws java.io.IOException
path
- The full path to the image file.java.io.IOException
public void addThumbnail(java.lang.String filename, java.io.InputStream data) throws java.io.IOException
filename
- The full path to the image file.data
- the image datajava.io.IOException
public PackageProperties getPackageProperties() throws InvalidFormatException
InvalidFormatException
public PackagePart getPart(PackagePartName partName)
partName
- Part name of the part to retrieve.null
.public java.util.ArrayList<PackagePart> getPartsByContentType(java.lang.String contentType)
contentType
- The content type criteria.public java.util.ArrayList<PackagePart> getPartsByRelationshipType(java.lang.String relationshipType)
relationshipType
- Relationship type.null
.public java.util.List<PackagePart> getPartsByName(java.util.regex.Pattern namePattern)
namePattern
- The pattern for matching the namespublic PackagePart getPart(PackageRelationship partRel)
partRel
- The part relationship uses to retrieve the part.public java.util.ArrayList<PackagePart> getParts() throws InvalidFormatException
InvalidFormatException
- if the package is not valid.public PackagePart createPart(PackagePartName partName, java.lang.String contentType)
partName
- Part name.contentType
- Part content type.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.createPartImpl(PackagePartName, String, boolean)
public PackagePart createPart(PackagePartName partName, java.lang.String contentType, java.io.ByteArrayOutputStream content)
partName
- Part name of the part to create.contentType
- type associated with the filecontent
- the contents to add. In order to have faster operation in
document merge, the data are stored in memory not on a hard
diskcreatePart(PackagePartName, String)
protected PackagePart addPackagePart(PackagePart part)
part
- The part to add (or replace).InvalidOperationException
- 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.public void removePart(PackagePart part)
part
- The part to remove. If null
, skip the action.removePart(PackagePartName)
public void removePart(PackagePartName partName)
partName
- The part name of the part to remove.public void removePartRecursive(PackagePartName partName) throws InvalidFormatException
partName
- The name of the part to delete.InvalidFormatException
- Throws if the associated relationship part of the specified
part is not valid.public void deletePart(PackagePartName partName)
partName
- Name of the part to deletepublic void deletePartRecursive(PackagePartName partName)
partName
- Name of the part to deletepublic boolean containPart(PackagePartName partName)
partName
- Part name to check.public PackageRelationship addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType, java.lang.String relID)
addRelationship
in interface RelationshipSource
targetPartName
- Target part name.targetMode
- Target mode, either Internal or External.relationshipType
- Relationship type.relID
- ID of the relationship.PackageRelationshipTypes
public PackageRelationship addRelationship(PackagePartName targetPartName, TargetMode targetMode, java.lang.String relationshipType)
addRelationship
in interface RelationshipSource
targetPartName
- Target part name.targetMode
- Target mode, either Internal or External.relationshipType
- Relationship type.PackageRelationshipTypes
public PackageRelationship addExternalRelationship(java.lang.String target, java.lang.String relationshipType)
addExternalRelationship
in interface RelationshipSource
target
- External target of the relationshiprelationshipType
- Type of relationship.RelationshipSource.addExternalRelationship(java.lang.String,
java.lang.String)
public PackageRelationship addExternalRelationship(java.lang.String target, java.lang.String relationshipType, java.lang.String id)
addExternalRelationship
in interface RelationshipSource
target
- External target of the relationshiprelationshipType
- Type of relationship.id
- Relationship unique id.RelationshipSource.addExternalRelationship(java.lang.String,
java.lang.String)
public void removeRelationship(java.lang.String id)
removeRelationship
in interface RelationshipSource
id
- Id of the relationship to delete.public PackageRelationshipCollection getRelationships()
getRelationships
in interface RelationshipSource
InvalidOperationException
- if a read operation is done on a write only package.getRelationshipsHelper(String)
public PackageRelationshipCollection getRelationshipsByType(java.lang.String relationshipType)
getRelationshipsByType
in interface RelationshipSource
relationshipType
- The filter specifying the relationship type.public void clearRelationships()
clearRelationships
in interface RelationshipSource
public void ensureRelationships()
public PackageRelationship getRelationship(java.lang.String id)
RelationshipSource
getRelationship
in interface RelationshipSource
id
- ID of the package relationship to retrieve.RelationshipSource.getRelationship(java.lang.String)
public boolean hasRelationships()
RelationshipSource
hasRelationships
in interface RelationshipSource
RelationshipSource.hasRelationships()
public boolean isRelationshipExists(PackageRelationship rel)
RelationshipSource
isRelationshipExists
in interface RelationshipSource
rel
- The relationship to check.RelationshipSource.isRelationshipExists(org.apache.poi.openxml4j.opc.PackageRelationship)
public void addMarshaller(java.lang.String contentType, PartMarshaller marshaller)
contentType
- The content type to bind to the specified marshaller.marshaller
- The marshaller to register with the specified content type.public void addUnmarshaller(java.lang.String contentType, PartUnmarshaller unmarshaller)
contentType
- The content type to bind to the specified unmarshaller.unmarshaller
- The unmarshaller to register with the specified content type.public void removeMarshaller(java.lang.String contentType)
contentType
- The content type associated with the marshaller to remove.public void removeUnmarshaller(java.lang.String contentType)
contentType
- The content type associated with the unmarshaller to remove.public PackageAccess getPackageAccess()
@NotImplemented public boolean validatePackage(OPCPackage pkg) throws InvalidFormatException
InvalidFormatException
public void save(java.io.File targetFile) throws java.io.IOException
targetFile
- Destination file.java.io.IOException
- Throws if an IO exception occur.save(OutputStream)
public void save(java.io.OutputStream outputStream) throws java.io.IOException
outputStream
- The stream to save the package.java.io.IOException
saveImpl(OutputStream)
protected abstract PackagePart createPartImpl(PackagePartName partName, java.lang.String contentType, boolean loadRelationships)
partName
- URI of the part to create.contentType
- Content type of the part to create.protected abstract void removePartImpl(PackagePartName partName)
partName
- The URI of the part to delete.protected abstract void flushImpl()
protected abstract void closeImpl() throws java.io.IOException
java.io.IOException
protected abstract void revertImpl()
protected abstract void saveImpl(java.io.OutputStream outputStream) throws java.io.IOException
outputStream
- The output stream use to save this package.java.io.IOException
protected abstract PackagePartCollection getPartsImpl() throws InvalidFormatException
InvalidFormatException
public boolean replaceContentType(java.lang.String oldContentType, java.lang.String newContentType)
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();
oldContentType
- the content type to be replacednewContentType
- the replacementpublic void registerPartAndContentType(PackagePart part)
part
- The part to add.public void unregisterPartAndContentType(PackagePartName partName)
partName
- The part name of the part to remove.public int getUnusedPartIndex(java.lang.String nameTemplate) throws InvalidFormatException
nameTemplate
- The template for new part names containing a '#'
for the index,
e.g. "/ppt/slides/slide#.xml"InvalidFormatException
- if the nameTemplate is null or doesn't contain
the index char (#) or results in an invalid part nameCopyright 2020 The Apache Software Foundation or its licensors, as applicable.