org.odftoolkit.odfdom.pkg
Class OdfPackageDocument

java.lang.Object
  extended by org.odftoolkit.odfdom.pkg.OdfPackageDocument
All Implemented Interfaces:
Closeable
Direct Known Subclasses:
OdfSchemaDocument

public class OdfPackageDocument
extends Object
implements Closeable

The package layer described by the ODF 1.2 Package specification is independent of the above ODF XML layer described by the ODF 1.2 XML Schema specification. Still the abstract concept of documents exist in the ODF Package layer.


Nested Class Summary
protected static class OdfPackageDocument.Resource
          Helper class to receive an ODF document template for new documents from the environment (ie.
 
Field Summary
protected  String mDocumentMediaType
          The mediatype of the ODF package document.
protected  String mDocumentPathInPackage
          The internal path to the document relative to the ODF package
protected  OdfPackage mPackage
          The ODF package containing the document
protected static String ROOT_DOCUMENT_PATH
          The path of the root document
 
Constructor Summary
protected OdfPackageDocument(OdfPackage pkg, String internalPath, String mediaTypeString)
          Creates a new OdfPackageDocument.
 
Method Summary
 void close()
          Close the OdfPackageDocument, its OdfPackage and release all temporary created data.
protected  void flushDoms()
          Flush the existing DOM to the document to get in advantage of the recent changes from the DOM
 String getDocumentPath()
          Get the relative path for an embedded ODF document.
 OdfFileDom getFileDom(String internalPath)
           
 String getMediaTypeString()
           
 OdfPackage getPackage()
          Retreives the OdfPackage for this OdfPackageDocument.
 void insertDocument(OdfPackageDocument newDocument, String documentPath)
          Embed an OdfPackageDocument to the current OdfPackageDocument.
protected static boolean isExternalReference(String ref)
          Checks if the given reference is a reference, which points outside the ODF package Only relative path are allowed with the exception of a single slash '/' representing the root document.
 boolean isRootDocument()
           
static OdfPackageDocument loadDocument(String documentPath)
          Loads an OdfPackageDocument from the provided path.
 OdfPackageDocument loadSubDocument(String documentPath)
          Returns an embedded OdfPackageDocument from the given package path.
protected static String normalizeDocumentPath(String documentPath)
          Ensure the document path for is valid and gurantee unique encoding by normalizing the path.
 void removeDocument(String internDocumentPath)
          Removes an embedded ODF document from the ODF Package.
 void save(File file)
          Save the document to a given file.
 void save(String documentPath)
          Save the document to given path.
protected  void setMediaTypeString(String mediaTypeString)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ROOT_DOCUMENT_PATH

protected static final String ROOT_DOCUMENT_PATH
The path of the root document

See Also:
Constant Field Values

mPackage

protected OdfPackage mPackage
The ODF package containing the document


mDocumentPathInPackage

protected String mDocumentPathInPackage
The internal path to the document relative to the ODF package


mDocumentMediaType

protected String mDocumentMediaType
The mediatype of the ODF package document. Note: Not necessarily an ODF XML mediatype as specified in ODF 1.2 part1

Constructor Detail

OdfPackageDocument

protected OdfPackageDocument(OdfPackage pkg,
                             String internalPath,
                             String mediaTypeString)
Creates a new OdfPackageDocument.

Parameters:
pkg - - the ODF Package that contains the document. A baseURL is being generated based on its location.
internalPath - - the directory path within the package from where the document should be loaded.
mediaTypeString - - media type of stream. If unknown null can be used.
Method Detail

loadDocument

public static OdfPackageDocument loadDocument(String documentPath)
                                       throws Exception
Loads an OdfPackageDocument from the provided path.

OdfPackageDocument relies on the file being available for read access over the whole lifecycle of OdfDocument.

Parameters:
documentPath - - the path from where the document can be loaded
Returns:
the OpenDocument from the given path or NULL if the media type is not supported by ODFDOM.
Throws:
Exception - - if the document could not be created.

loadSubDocument

public OdfPackageDocument loadSubDocument(String documentPath)
Returns an embedded OdfPackageDocument from the given package path.

Parameters:
documentPath - to the document within the package. The path is relative the current document path.
Returns:
an embedded OdfPackageDocument

getMediaTypeString

public String getMediaTypeString()
Returns:
the mediatype of this document

setMediaTypeString

protected final void setMediaTypeString(String mediaTypeString)
Parameters:
mediaTypeString - for the mediatype of this document

getPackage

public OdfPackage getPackage()
Retreives the OdfPackage for this OdfPackageDocument.

Returns:
the OdfPackage that contains this OdfPackageDocument.

getDocumentPath

public String getDocumentPath()
Get the relative path for an embedded ODF document.

Returns:
path to the directory of the embedded ODF document (relative to ODF package root).

removeDocument

public void removeDocument(String internDocumentPath)
Removes an embedded ODF document from the ODF Package. All files within the embedded document directory will be removed.

Parameters:
internDocumentPath - path to the directory of the embedded ODF document (always relative to the package path of the current document).

isRootDocument

public boolean isRootDocument()
Returns:
true if the document is at the root level of the package

isExternalReference

protected static boolean isExternalReference(String ref)
Checks if the given reference is a reference, which points outside the ODF package Only relative path are allowed with the exception of a single slash '/' representing the root document.

Parameters:
ref - the file reference to be checked
Returns:
true if the reference is an package external reference

normalizeDocumentPath

protected static String normalizeDocumentPath(String documentPath)
Ensure the document path for is valid and gurantee unique encoding by normalizing the path.

Parameters:
documentPath - the destination directory of the document. The path should end with a '/'.
Returns:
the documentPath after normalization.
See Also:
OdfPackage.normalizeDirectoryPath(java.lang.String)

save

public void save(String documentPath)
          throws Exception
Save the document to given path.

When save the embedded document to a stand alone document, all the file entries of the embedded document will be copied to a new document package. If the embedded document is outside of the current document directory, you have to embed it to the sub directory and refresh the link of the embedded document. You should reload it from the given path to get the saved embedded document.

Parameters:
documentPath - - the path to the package document
Throws:
Exception - if the document could not be saved

save

public void save(File file)
          throws Exception
Save the document to a given file.

If the input file has been cached (this is the case when loading from an InputStream), the input file can be overwritten.

Otherwise it's allowed to overwrite the input file as long as the same path name is used that was used for loading (no symbolic link foo2.odt pointing to the loaded file foo1.odt, no network path X:\foo.odt pointing to the loaded file D:\foo.odt).

When saving the embedded document to a stand alone document, all files of the embedded document will be copied to a new document package. If the embedded document is outside of the current document directory, you have to embed it to the sub directory and refresh the link of the embedded document. You should reload it from the given file to get the saved embedded document.

Parameters:
file - - the file to save the document
Throws:
Exception - if the document could not be saved

flushDoms

protected void flushDoms()
Flush the existing DOM to the document to get in advantage of the recent changes from the DOM


insertDocument

public void insertDocument(OdfPackageDocument newDocument,
                           String documentPath)
Embed an OdfPackageDocument to the current OdfPackageDocument. All the file entries of child document will be embedded as well to the current document package.

Parameters:
newDocument - the OdfPackageDocument to be embedded.
documentPath - to the directory the ODF document should be inserted (relative to the root of this document).

getFileDom

public OdfFileDom getFileDom(String internalPath)
                      throws Exception
Parameters:
internalPath - path to the XML file relative to package root
Returns:
the typed DOM of the given file
Throws:
Exception

close

public void close()
Close the OdfPackageDocument, its OdfPackage and release all temporary created data. Acter execution of this method, this class is no longer usable. Do this as the last action to free resources. Closing an already closed document has no effect.

Specified by:
close in interface Closeable


Copyright © 2008-2011 The Apache Software Foundation. All Rights Reserved.