Class OdfPackage
- java.lang.Object
-
- org.odftoolkit.odfdom.pkg.OdfPackage
-
- All Implemented Interfaces:
Closeable
,AutoCloseable
public class OdfPackage extends Object implements Closeable
OdfPackage represents the package view to an OpenDocument document. The OdfPackage will be created from an ODF document and represents a copy of the loaded document, where files can be inserted and deleted. The changes take effect, when the OdfPackage is being made persisted by save().
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
OdfPackage.OdfFile
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
close()
Close the OdfPackage after it is no longer needed.boolean
contains(String internalPath)
Check existence of a file in the package.void
freeMemory()
String
getBaseURI()
byte[]
getBytes(String internalPath)
Get package (sub-) content as byte arrayOdfPackageDocument
getCachedDocument(String internalPath)
Deprecated.This method is only added temporary as workaround for the IBM fork using different DOC classes.Set<String>
getDocumentPaths()
Method returns the paths of all document within the package.Set<String>
getDocumentPaths(String mediaTypeString)
Method returns the paths of all document within the package matching the given criteria.Document
getDom(String internalPath)
Gets org.w3c.dom.Document for XML file contained in package.EntityResolver
getEntityResolver()
Get EntityResolver to be used in XML Parsers which can resolve content inside the OdfPackageErrorHandler
getErrorHandler()
Return the current error handler used for ODF validation.OdfFileEntry
getFileEntry(String internalPath)
Get an OdfFileEntry for the internalPath NOTE: This method should be better moved to a DOM inherited Manifest classSet<String>
getFilePaths()
Get a OdfFileEntries from the manifest file (i.e.InputStream
getInputStream()
Gets the InputStream containing whole OdfPackage.InputStream
getInputStream(String internalPath)
Get the latest version of package content as InputStream, as it would be saved.InputStream
getInputStream(String internalPath, boolean useOriginal)
Get the latest version of package content as InputStream, as it would be saved.OdfManifestDom
getManifestDom()
String
getMediaTypeString()
Get the media type of the ODF package (equal to media type of ODF root document)String
getMediaTypeString(String internalPath)
Get the media type of the ODF file or document (ie.String
getNextMarkupId()
OdfPackageDocument
getRootDocument()
Map<String,Object>
getRunTimeConfiguration()
Run-time configuration such as special logging or maximum table size to create operations from are stored in this map.long
getSize(String internalPath)
Get the size of an internal file from the package.URIResolver
getURIResolver()
Get URIResolver to be used in XSL Transformations which can resolve content inside the OdfPackagevoid
insert(byte[] fileBytes, String internalPath, String mediaTypeString)
Inserts a byte array into OdfPackage.void
insert(InputStream fileStream, String internalPath, String mediaType)
Inserts InputStream into an OdfPackage.void
insert(URI sourceURI, String internalPath, String mediaType)
Inserts an external file into an OdfPackage.void
insert(Document fileDOM, String internalPath, String mediaType)
Insert DOM tree into OdfPackage.void
insertDocument(OdfPackageDocument sourceDocument, String destinationPath)
Embed an OdfPackageDocument to the current OdfPackage.OutputStream
insertOutputStream(String internalPath)
Insert the OutputStream for into OdfPackage.OutputStream
insertOutputStream(String internalPath, String mediaType)
Insert the OutputStream - to be filled after method - when stream is closed into OdfPackage.static boolean
isExternalReference(String internalPath)
Checks if the given reference is a reference, which points outside the ODF packageOdfPackageDocument
loadDocument(String internalPath)
Returns on ODF documents based a given mediatype.static OdfPackage
loadPackage(File pkgFile)
Loads an OdfPackage from the OpenDocument provided by a File.static OdfPackage
loadPackage(File pkgFile, String password)
Loads an OdfPackage from the given File.static OdfPackage
loadPackage(File pkgFile, String password, ErrorHandler errorHandler)
Loads an OdfPackage from the given File.static OdfPackage
loadPackage(File pkgFile, ErrorHandler errorHandler)
Loads an OdfPackage from the given File.static OdfPackage
loadPackage(InputStream packageStream)
Creates an OdfPackage from the given InputStream.static OdfPackage
loadPackage(InputStream packageStream, String baseURI, ErrorHandler errorHandler)
Creates an OdfPackage from the given InputStream.static OdfPackage
loadPackage(InputStream packageStream, Map<String,Object> configuration)
Creates an OdfPackage from the given InputStream.static OdfPackage
loadPackage(String path)
Loads an OdfPackage from the given documentURL.void
remove(String internalPath)
Removes a single file from the package.void
removeDocument(String internalPath)
Removes a document from the package via its path.void
save(File pkgFile)
Save package to a given File.void
save(OutputStream odfStream)
Saves the package to a givenOutputStream
.void
save(String odfPath)
Save the package to given documentURL.void
setErrorHandler(ErrorHandler handler)
Allow an application to register an error event handler.void
setPassword(String password)
Sets the password of this package.
-
-
-
Method Detail
-
freeMemory
public void freeMemory()
-
loadPackage
public static OdfPackage loadPackage(String path) throws SAXException, IOException
Loads an OdfPackage from the given documentURL.OdfPackage relies on the file being available for read access over the whole life-cycle of OdfPackage.
- Parameters:
path
- - the documentURL to the ODF package- Returns:
- the OpenDocument document represented as an OdfPackage
- Throws:
SAXException
- if there's an XML- or validation-related error while loading the packageIOException
- if there's an I/O error while loading the package
-
loadPackage
public static OdfPackage loadPackage(File pkgFile) throws SAXException, IOException
Loads an OdfPackage from the OpenDocument provided by a File.OdfPackage relies on the file being available for read access over the whole life-cycle of OdfPackage.
- Parameters:
pkgFile
- - the ODF Package- Returns:
- the OpenDocument document represented as an OdfPackage
- Throws:
SAXException
- if there's an XML- or validation-related error while loading the packageIOException
- if there's an I/O error while loading the package
-
loadPackage
public static OdfPackage loadPackage(InputStream packageStream) throws SAXException, IOException
Creates an OdfPackage from the given InputStream.Since an InputStream does not provide the arbitrary (non sequential) read access needed by OdfPackage, the InputStream is cached. This usually takes more time compared to the other loadPackage methods.
- Parameters:
packageStream
- - an inputStream representing the ODF package- Returns:
- the OpenDocument document represented as an OdfPackage
- Throws:
SAXException
- if there's an XML- or validation-related error while loading the packageIOException
- if there's an I/O error while loading the package
-
loadPackage
public static OdfPackage loadPackage(InputStream packageStream, Map<String,Object> configuration) throws Exception
Creates an OdfPackage from the given InputStream.Since an InputStream does not provide the arbitrary (non sequential) read access needed by OdfPackage, the InputStream is cached. This usually takes more time compared to the other loadPackage methods.
- Parameters:
packageStream
- - an inputStream representing the ODF packageconfiguration
- - key/value pairs of user given run-time settings (configuration) For instance, the maximum size of tables.- Returns:
- the OpenDocument document represented as an OdfPackage
- Throws:
Exception
- - if the package could not be loaded
-
loadPackage
public static OdfPackage loadPackage(InputStream packageStream, String baseURI, ErrorHandler errorHandler) throws SAXException, IOException
Creates an OdfPackage from the given InputStream.OdfPackage relies on the file being available for read access over the whole life-cycle of OdfPackage.
- Parameters:
packageStream
- - an inputStream representing the ODF packagebaseURI
- allows to explicitly set the base URI from the document, As the URL can not be derived from a stream. In addition it is possible to set the baseURI to any arbitrary URI, e.g. an URN. One usage of the baseURI to describe the source of validation exception thrown by the ErrorHandler.errorHandler
- - SAX ErrorHandler used for ODF validation- Throws:
SAXException
- if there's an XML- or validation-related error while loading the packageIOException
- if there's an I/O error while loading the package- See Also:
getErrorHandler()
-
loadPackage
public static OdfPackage loadPackage(File pkgFile, ErrorHandler errorHandler) throws SAXException, IOException
Loads an OdfPackage from the given File.OdfPackage relies on the file being available for read access over the whole life-cycle of OdfPackage.
- Parameters:
pkgFile
- - the ODF Package. A baseURL is being generated based on its location.errorHandler
- - SAX ErrorHandler used for ODF validation.- Throws:
SAXException
- if there's an XML- or validation-related error while loading the packageIOException
- if there's an I/O error while loading the package- See Also:
getErrorHandler()
-
getRunTimeConfiguration
public Map<String,Object> getRunTimeConfiguration()
Run-time configuration such as special logging or maximum table size to create operations from are stored in this map.- Returns:
- key/value pairs of user given run-time settings (configuration)
-
loadPackage
public static OdfPackage loadPackage(File pkgFile, String password) throws SAXException, IOException
Loads an OdfPackage from the given File.OdfPackage relies on the file being available for read access over the whole life-cycle of OdfPackage.
- Parameters:
pkgFile
- - the ODF Package. A baseURL is being generated based on its location.password
- - the ODF Package password.- Throws:
SAXException
- if there's an XML- or validation-related error while loading the packageIOException
- if there's an I/O error while loading the package- See Also:
getErrorHandler()
-
loadPackage
public static OdfPackage loadPackage(File pkgFile, String password, ErrorHandler errorHandler) throws SAXException, IOException
Loads an OdfPackage from the given File.OdfPackage relies on the file being available for read access over the whole life-cycle of OdfPackage.
- Parameters:
pkgFile
- - the ODF Package. A baseURL is being generated based on its location.password
- - the ODF Package password.errorHandler
- - SAX ErrorHandler used for ODF validation.- Throws:
SAXException
- if there's an XML- or validation-related error while loading the packageIOException
- if there's an I/O error while loading the package- See Also:
getErrorHandler()
-
getBaseURI
public String getBaseURI()
- Returns:
- The URI to the ODF package, usually the URL, where this ODF package is located. If the package has not URI NULL is returned. This is the case if the package was new created without an URI and not saved before.
-
loadDocument
public OdfPackageDocument loadDocument(String internalPath)
Returns on ODF documents based a given mediatype.- Parameters:
internalPath
- path relative to the package root, where the document should be loaded.- Returns:
- The ODF document, which mediatype depends on the parameter or NULL if media type were not supported.
-
getCachedDocument
@Deprecated public OdfPackageDocument getCachedDocument(String internalPath)
Deprecated.This method is only added temporary as workaround for the IBM fork using different DOC classes. Until the registering of DOC documents to the PKG layer has been finished.- Parameters:
internalPath
- path relative to the package root, where the document should be inserted.- Returns:
- an already open OdfPackageDocument via its path, otherwise NULL.
-
removeDocument
public void removeDocument(String internalPath)
Removes a document from the package via its path. Independent if it was already opened or not.- Parameters:
internalPath
- path relative to the package root, where the document should be removed.
-
getRootDocument
public OdfPackageDocument getRootDocument()
-
getManifestDom
public OdfManifestDom getManifestDom()
-
getMediaTypeString
public String getMediaTypeString(String internalPath)
Get the media type of the ODF file or document (ie. a directory). A directory with a mediatype can be loaded asOdfPackageDocument
. Note: A directoy is represented by in the package as directory with media type- Parameters:
internalPath
- within the package of the file or document.- Returns:
- the mediaType for the resource of the given path
-
getMediaTypeString
public String getMediaTypeString()
Get the media type of the ODF package (equal to media type of ODF root document)- Returns:
- the mediaType string of this ODF package
-
getFileEntry
public OdfFileEntry getFileEntry(String internalPath)
Get an OdfFileEntry for the internalPath NOTE: This method should be better moved to a DOM inherited Manifest class- Parameters:
internalPath
- The relative package path within the ODF package- Returns:
- The manifest file entry will be returned.
-
getFilePaths
public Set<String> getFilePaths()
Get a OdfFileEntries from the manifest file (i.e. /META/manifest.xml")- Returns:
- The paths of the manifest file entries will be returned.
-
contains
public boolean contains(String internalPath)
Check existence of a file in the package.- Parameters:
internalPath
- The relative package documentURL within the ODF package- Returns:
- True if there is an entry and a file for the given documentURL
-
save
public void save(String odfPath) throws SAXException, IOException
Save the package to given documentURL.- Parameters:
odfPath
- - the path to the ODF package destination- Throws:
IOException
- - if the package could not be savedSAXException
-
save
public void save(File pkgFile) throws SAXException, IOException
Save package to a given File. After saving it is still necessary to close the package to have again full access about the file.- Parameters:
pkgFile
- - the File to save the ODF package to- Throws:
IOException
- - if the package could not be savedSAXException
-
save
public void save(OutputStream odfStream) throws SAXException, IOException
Saves the package to a givenOutputStream
. The given stream is not closed by this method.- Parameters:
odfStream
- the output stream- Throws:
IOException
- if an I/O error occurs while saving the packageSAXException
-
setPassword
public void setPassword(String password)
Sets the password of this package. if password is not null, package will be encrypted when save.- Parameters:
password
- password- Since:
- 0.8.9
-
close
public void close()
Close the OdfPackage after it is no longer needed. Even after saving it is still necessary to close the package to have again full access about the file. Closing the OdfPackage will release all temporary created data. Do this as the last action to free resources. Closing an already closed document has no effect.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
insert
public void insert(Document fileDOM, String internalPath, String mediaType)
Insert DOM tree into OdfPackage. An existing file will be replaced.- Parameters:
fileDOM
- - XML DOM tree to be inserted as file.internalPath
- - relative documentURL where the DOM tree should be inserted as XML filemediaType
- - media type of stream. Set to null if unknown- Throws:
Exception
- when the DOM tree could not be inserted
-
insertDocument
public void insertDocument(OdfPackageDocument sourceDocument, String destinationPath)
Embed an OdfPackageDocument to the current OdfPackage. All the file entries of child document will be inserted.- Parameters:
sourceDocument
- the OdfPackageDocument to be embedded.destinationPath
- path to the directory the ODF document should be inserted (relative to ODF package root).
-
getDocumentPaths
public Set<String> getDocumentPaths()
Method returns the paths of all document within the package.- Returns:
- A set of paths of all documents of the package, including the root document.
-
getDocumentPaths
public Set<String> getDocumentPaths(String mediaTypeString)
Method returns the paths of all document within the package matching the given criteria.- Parameters:
mediaTypeString
- limits the desired set of document paths to documents of the given mediaType- Returns:
- A set of paths of all documents of the package, including the root document, that match the given parameter.
-
getDom
public Document getDom(String internalPath) throws SAXException, ParserConfigurationException, IllegalArgumentException, TransformerConfigurationException, TransformerException, IOException
Gets org.w3c.dom.Document for XML file contained in package.- Parameters:
internalPath
- to a file within the Odf Package (eg. content.xml)- Returns:
- an org.w3c.dom.Document
- Throws:
SAXException
ParserConfigurationException
IOException
IllegalArgumentException
TransformerConfigurationException
TransformerException
-
insert
public void insert(URI sourceURI, String internalPath, String mediaType) throws Exception
Inserts an external file into an OdfPackage. An existing file will be replaced.- Parameters:
sourceURI
- - the source URI to the file to be inserted into the package.internalPath
- - relative documentURL where the tree should be inserted as XML filemediaType
- - media type of stream. Set to null if unknown- Throws:
Exception
- In case the file could not be saved
-
insert
public void insert(InputStream fileStream, String internalPath, String mediaType) throws IOException
Inserts InputStream into an OdfPackage. An existing file will be replaced.- Parameters:
fileStream
- - the stream of the file to be inserted into the ODF package.internalPath
- - relative documentURL where the tree should be inserted as XML filemediaType
- - media type of stream. Set to null if unknown- Throws:
IOException
-
insert
public void insert(byte[] fileBytes, String internalPath, String mediaTypeString)
Inserts a byte array into OdfPackage. An existing file will be replaced. If the byte array is NULL a directory with the given mimetype will be created.- Parameters:
fileBytes
- - data of the file stream to be stored in package. If NULL a directory with the given mimetype will be created.internalPath
- - path of the file or directory relative to the package root.mediaTypeString
- - media type of stream. If unknown null can be used.
-
getBytes
public byte[] getBytes(String internalPath)
Get package (sub-) content as byte array- Parameters:
internalPath
- relative documentURL to the package content- Returns:
- the unzipped package content as byte array
- Throws:
Exception
-
getInputStream
public InputStream getInputStream(String internalPath)
Get the latest version of package content as InputStream, as it would be saved. This might not be the original version once loaded from the package.- Parameters:
internalPath
- of the desired stream.- Returns:
- Inputstream of the ODF file within the package for the given path.
-
getInputStream
public InputStream getInputStream(String internalPath, boolean useOriginal)
Get the latest version of package content as InputStream, as it would be saved. This might not be the original version once loaded from the package.- Parameters:
internalPath
- of the desired stream.useOriginal
- true uses the stream as loaded from the ZIP. False will return even modified file content as a stream.- Returns:
- Inputstream of the ODF file within the package for the given path.
-
getInputStream
public InputStream getInputStream() throws IOException, SAXException
Gets the InputStream containing whole OdfPackage.- Returns:
- the ODF package as input stream
- Throws:
IOException
- - if the package could not be readSAXException
-
insertOutputStream
public OutputStream insertOutputStream(String internalPath) throws Exception
Insert the OutputStream for into OdfPackage. An existing file will be replaced.- Parameters:
internalPath
- - relative documentURL where the DOM tree should be inserted as XML file- Returns:
- outputstream for the data of the file to be stored in package
- Throws:
Exception
- when the DOM tree could not be inserted
-
insertOutputStream
public OutputStream insertOutputStream(String internalPath, String mediaType) throws IOException
Insert the OutputStream - to be filled after method - when stream is closed into OdfPackage. An existing file will be replaced.- Parameters:
internalPath
- - relative documentURL where the DOM tree should be inserted as XML filemediaType
- - media type of stream- Returns:
- outputstream for the data of the file to be stored in package
- Throws:
IOException
- when the DOM tree could not be inserted
-
remove
public void remove(String internalPath)
Removes a single file from the package.- Parameters:
internalPath
- of the file relative to the package root
-
getSize
public long getSize(String internalPath)
Get the size of an internal file from the package.- Parameters:
internalPath
- of the file relative to the package root- Returns:
- the size of the file in bytes or -1 if the size could not be received.
-
getEntityResolver
public EntityResolver getEntityResolver()
Get EntityResolver to be used in XML Parsers which can resolve content inside the OdfPackage- Returns:
- a SAX EntityResolver
-
getURIResolver
public URIResolver getURIResolver()
Get URIResolver to be used in XSL Transformations which can resolve content inside the OdfPackage- Returns:
- a TraX Resolver
-
isExternalReference
public static boolean isExternalReference(String internalPath)
Checks if the given reference is a reference, which points outside the ODF package- Parameters:
internalPath
- the file reference to be checked- Returns:
- true if the reference is an package external reference
-
setErrorHandler
public void setErrorHandler(ErrorHandler handler)
Allow an application to register an error event handler.If the application does not register an error handler, all error events reported by the ODFDOM (e.g. the SAX Parser) will be silently ignored; however, normal processing may not continue. It is highly recommended that all ODF applications implement an error handler to avoid unexpected bugs.
Applications may register a new or different handler in the middle of a parse, and the ODFDOM will begin using the new handler immediately.
- Parameters:
handler
- The error handler.- See Also:
getErrorHandler()
-
getErrorHandler
public ErrorHandler getErrorHandler()
Return the current error handler used for ODF validation.- Returns:
- The current error handler, or null if none has been registered and validation is disabled.
- See Also:
setErrorHandler(org.xml.sax.ErrorHandler)
-
getNextMarkupId
public String getNextMarkupId()
- Returns:
- counter for ids that are not allowed to be saved (otherwise it is not guaranteed that this id is unique)
-
-