Package org.odftoolkit.odfdom.doc

Class OdfDocument

java.lang.Object

org.odftoolkit.odfdom.pkg.OdfPackageDocument

org.odftoolkit.odfdom.dom.OdfSchemaDocument

org.odftoolkit.odfdom.doc.OdfDocument

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

OdfChartDocument, OdfGraphicsDocument, OdfImageDocument, OdfPresentationDocument, OdfSpreadsheetDocument, OdfTextDocument

public abstract class OdfDocument
extends OdfSchemaDocument

This abstract class is representing one of the possible ODF documents.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	OdfDocument.OdfMediaType	This enum contains all possible media types of OpenDocument documents.
static class	OdfDocument.UnicodeGroup	Unicode characters are in general divided by office applications into three different groups.

Nested classes/interfaces inherited from class org.odftoolkit.odfdom.dom.OdfSchemaDocument

OdfSchemaDocument.OdfXMLFile

Nested classes/interfaces inherited from class org.odftoolkit.odfdom.pkg.OdfPackageDocument

OdfPackageDocument.Resource

Field Summary

Fields

Modifier and Type	Field	Description
protected Boolean	mHasCollaboration

Fields inherited from class org.odftoolkit.odfdom.dom.OdfSchemaDocument

mContentDom, mJsonOperationQueue, mMetaDom, mSettingsDom, mStylesDom

Fields inherited from class org.odftoolkit.odfdom.pkg.OdfPackageDocument

mDocumentMediaType, mDocumentPathInPackage, mPackage, ROOT_DOCUMENT_PATH

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	OdfDocument(OdfPackage pkg, String internalPath, OdfDocument.OdfMediaType mediaType)

Method Summary

Modifier and Type	Method	Description
void	addAnnotation(String name, OfficeAnnotationElement element)
void	close()	Close the document and release all temporary created data.
OfficeAnnotationElement	getAnnotation(String name)
OdfElement	getContentRoot()	Get the content root of a document.
Set<String>	getFontNames()	This is a temporary solution to know about the fonts within the documents.
Locale	getLocale(OdfDocument.UnicodeGroup unicodeGroup)	This method will return Locale, which presents the default language and country information settings in this document
protected OdfDocument.OdfMediaType	getOdfMediaType()	Gets the media type of the OdfDocument
OdfOfficeMeta	getOfficeMetadata()	Get the meta data feature instance of the current document
OdfTable	getTableByName(String name)	Return an instance of table feature with the specific table name.
List<OdfTable>	getTableList()	Deprecated.
List<OdfTable>	getTableList(boolean doRecursiveSearch)	Return a list of table features in this document.
static OdfDocument.UnicodeGroup	getUnicodeGroup(Locale locale)	Similar to OpenOffice.org, ODFDOM assumes that every Locale is related to one of the three Unicodes Groups, either CJK, CTL or Western.
String	getUniqueAnnotationName()
Boolean	hasCollaboration()
static OdfDocument	loadDocument(File file)	Loads the ODF root document from the ODF package provided as a File.
static OdfDocument	loadDocument(InputStream inStream)	Loads the ODF root document from the ODF package provided by a Stream.
static OdfDocument	loadDocument(InputStream inStream, Boolean enableCollaboration)	Loads the ODF root document from the ODF package provided by a Stream.
static OdfDocument	loadDocument(InputStream inStream, Map<String,Object> configuration)	Loads the ODF root document from the ODF package provided by a Stream.
static OdfDocument	loadDocument(InputStream inStream, Map<String,Object> configuration, Boolean enableCollaboration)	Loads the ODF root document from the ODF package provided by a Stream.
static OdfDocument	loadDocument(String documentPath)	Loads the ODF root document from the ODF package provided by its path.
static OdfDocument	loadDocument(OdfPackage odfPackage)	Loads the ODF root document from the ODF package.
static OdfDocument	loadDocument(OdfPackage odfPackage, Boolean enableCollaboration)	Loads the ODF root document from the ODF package.
static OdfDocument	loadDocument(OdfPackage odfPackage, String internalPath)	Creates an OdfDocument from the OpenDocument provided by an ODF package.
static OdfDocument	loadDocument(OdfPackage odfPackage, String internalPath, Boolean enableCollaboration)	Creates an OdfDocument from the OpenDocument provided by an ODF package.
OdfDocument	loadSubDocument(String documentPath)	Returns an embedded OdfPackageDocument from the given package path.
Map<String,OdfDocument>	loadSubDocuments()	Method returns all embedded OdfPackageDocuments, which match a valid OdfMediaType, of the current OdfPackageDocument.
Map<String,OdfDocument>	loadSubDocuments(OdfDocument.OdfMediaType desiredMediaType)	Method returns all embedded OdfPackageDocuments of sthe current OdfPackageDocument matching the according MediaType.
protected static OdfDocument	loadTemplate(OdfPackageDocument.Resource res, OdfDocument.OdfMediaType odfMediaType)	Loads the ODF root document from the given Resource.
protected static OdfDocument	loadTemplate(OdfPackageDocument.Resource res, OdfDocument.OdfMediaType odfMediaType, Boolean enableCollaboration)	Loads the ODF root document from the given Resource.
String	newImage(URI imageUri)	Insert an Image from the specified uri to the end of the OdfDocument.
void	removeAnnotation(String name)
protected void	removeCachedView()
void	save(File file)	Save the document to a given file.
void	save(OutputStream out)	Save the document to an OutputStream.
void	setLocale(Locale locale)	Set a locale information.
protected void	setOdfMediaType(OdfDocument.OdfMediaType odfMediaType)	Sets the media type of the OdfDocument
String	toString()
void	updateMetaData()	Update document meta data in the ODF document.

Methods inherited from class org.odftoolkit.odfdom.dom.OdfSchemaDocument

getBaseURI, getBookmarkRDFMetadata, getContentDom, getContentStream, getDocumentStyles, getFileDom, getInContentMetadata, getInContentMetadataFromCache, getJsonOperationQueue, getManifestRDFMetadata, getMasterPages, getMetaDom, getMetaStream, getOfficeMasterStyles, getOperations, getOrCreateDocumentStyles, getRDFMetadata, getRootComponent, getRootComponentElement, getSettingsDom, getSettingsStream, getStyleByDisplayName, getStyleByName, getStylesDom, getStylesStream, getTables, getTables, getXMLFilePath, setContentDom, setJsonOperationQueue, setMetaDom, setRootComponent, setSettingsDom, setStylesDom

Methods inherited from class org.odftoolkit.odfdom.pkg.OdfPackageDocument

flushDoms, getAbsoluteFilePath, getCachedDom, getDocumentPath, getFileDom, getMediaTypeString, getPackage, getXMLFileMetadata, insertDocument, isExternalReference, isRootDocument, normalizeDocumentPath, removeDocument, save, setMediaTypeString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

mHasCollaboration

protected Boolean mHasCollaboration

Constructor Detail

OdfDocument

protected OdfDocument(OdfPackage pkg,
                      String internalPath,
                      OdfDocument.OdfMediaType mediaType)
               throws SAXException

Throws:

SAXException

Method Detail

loadTemplate

protected static OdfDocument loadTemplate(OdfPackageDocument.Resource res,
                                          OdfDocument.OdfMediaType odfMediaType)
                                   throws Exception

Loads the ODF root document from the given Resource.

NOTE: Initial meta data (like the document creation time) will be added in this method.

Parameters:

res - a resource containing a package with a root document

odfMediaType - the media type of the root document

Returns:

the OpenDocument document or NULL if the media type is not supported by ODFDOM.

Throws:

Exception - - if the document could not be created.

loadTemplate

protected static OdfDocument loadTemplate(OdfPackageDocument.Resource res,
                                          OdfDocument.OdfMediaType odfMediaType,
                                          Boolean enableCollaboration)
                                   throws Exception

Loads the ODF root document from the given Resource.

NOTE: Initial meta data (like the document creation time) will be added in this method.

Parameters:

res - a resource containing a package with a root document

odfMediaType - the media type of the root document

enableCollaboration - - user changes equivalent for creating this document are gathered

Returns:

the OpenDocument document or NULL if the media type is not supported by ODFDOM.

Throws:

Exception - - if the document could not be created.

loadDocument

public static OdfDocument loadDocument(String documentPath)
                                throws Exception

Loads the ODF root document from the ODF package provided by its path.

OdfDocument relies on the file being available for read access over the whole life-cycle 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.

loadDocument

public static OdfDocument loadDocument(InputStream inStream,
                                       Map<String,Object> configuration)
                                throws Exception

Loads the ODF root document from the ODF package provided by a Stream.

Since an InputStream does not provide the arbitrary (non sequential) read access needed by OdfDocument, the InputStream is cached. This usually takes more time compared to the other createInternalDocument methods. An advantage of caching is that there are no problems overwriting an input file.

Parameters:

inStream - - the InputStream of the ODF document.

configuration - - key/value pairs of user given run-time settings (configuration)

Returns:

the document created from the given InputStream

Throws:

Exception - - if the document could not be created.

loadDocument

public static OdfDocument loadDocument(InputStream inStream,
                                       Map<String,Object> configuration,
                                       Boolean enableCollaboration)
                                throws Exception

Loads the ODF root document from the ODF package provided by a Stream.

Since an InputStream does not provide the arbitrary (non sequential) read access needed by OdfDocument, the InputStream is cached. This usually takes more time compared to the other createInternalDocument methods. An advantage of caching is that there are no problems overwriting an input file.

Parameters:

inStream - - the InputStream of the ODF document.

configuration - - key/value pairs of user given run-time settings (configuration)

enableCollaboration - - user changes equivalent for creating this document are gathered

Returns:

the document created from the given InputStream

Throws:

Exception - - if the document could not be created.

loadDocument

public static OdfDocument loadDocument(InputStream inStream)
                                throws Exception

Loads the ODF root document from the ODF package provided by a Stream.

Since an InputStream does not provide the arbitrary (non sequential) read access needed by OdfDocument, the InputStream is cached. This usually takes more time compared to the other createInternalDocument methods. An advantage of caching is that there are no problems overwriting an input file.

Parameters:

inStream - - the InputStream of the ODF document.

Returns:

the document created from the given InputStream

Throws:

Exception - - if the document could not be created.

loadDocument

public static OdfDocument loadDocument(InputStream inStream,
                                       Boolean enableCollaboration)
                                throws Exception

Loads the ODF root document from the ODF package provided by a Stream.

Since an InputStream does not provide the arbitrary (non sequential) read access needed by OdfDocument, the InputStream is cached. This usually takes more time compared to the other createInternalDocument methods. An advantage of caching is that there are no problems overwriting an input file.

Parameters:

inStream - - the InputStream of the ODF document.

enableCollaboration - - user changes equivalent for creating this document are gathered

Returns:

the document created from the given InputStream

Throws:

Exception - - if the document could not be created.

loadDocument

public static OdfDocument loadDocument(File file)
                                throws Exception

Loads the ODF root document from the ODF package provided as a File.

Parameters:

file - - a file representing the ODF document.

Returns:

the document created from the given File

Throws:

Exception - - if the document could not be created.

loadDocument

public static OdfDocument loadDocument(OdfPackage odfPackage)
                                throws Exception

Loads the ODF root document from the ODF package.

Parameters:

odfPackage - - the ODF package containing the ODF document.

Returns:

the root document of the given OdfPackage

Throws:

Exception - - if the ODF document could not be created.

loadDocument

public static OdfDocument loadDocument(OdfPackage odfPackage,
                                       Boolean enableCollaboration)
                                throws Exception

Loads the ODF root document from the ODF package.

Parameters:

odfPackage - - the ODF package containing the ODF document.

enableCollaboration - - user changes equivalent for creating this document are gathered

Returns:

the root document of the given OdfPackage

Throws:

Exception - - if the ODF document could not be created.

loadDocument

public static OdfDocument loadDocument(OdfPackage odfPackage,
                                       String internalPath)
                                throws Exception

Creates an OdfDocument from the OpenDocument provided by an ODF package.

Parameters:

odfPackage - - the ODF package containing the ODF document.

internalPath - - the path to the ODF document relative to the package root, or an empty String for the root document.

Returns:

the root document of the given OdfPackage

Throws:

Exception - - if the ODF document could not be created.

loadDocument

public static OdfDocument loadDocument(OdfPackage odfPackage,
                                       String internalPath,
                                       Boolean enableCollaboration)
                                throws Exception

Creates an OdfDocument from the OpenDocument provided by an ODF package.

Parameters:

odfPackage - - the ODF package containing the ODF document.

internalPath - - the path to the ODF document relative to the package root, or an empty String for the root document.

enableCollaboration - - user changes equivalent for creating this document are gathered

Returns:

the root document of the given OdfPackage

Throws:

Exception - - if the ODF document could not be created.

loadSubDocument

public OdfDocument loadSubDocument(String documentPath)

Returns an embedded OdfPackageDocument from the given package path.

Overrides:

loadSubDocument in class OdfPackageDocument

Parameters:

documentPath - to the ODF document within the package. The path is relative the current ODF document path.

Returns:

an embedded OdfPackageDocument

loadSubDocuments

public Map<String,OdfDocument> loadSubDocuments()

Method returns all embedded OdfPackageDocuments, which match a valid OdfMediaType, of the current OdfPackageDocument. Note: The root document is not part of the returned collection.

Returns:

a map with all embedded documents and their paths of the current OdfPackageDocument

loadSubDocuments

public Map<String,OdfDocument> loadSubDocuments(OdfDocument.OdfMediaType desiredMediaType)

Method returns all embedded OdfPackageDocuments of sthe current OdfPackageDocument matching the according MediaType. This is done by matching the subfolder entries of the manifest file with the given OdfMediaType.

Parameters:

desiredMediaType - media type of the documents to be returned (used as a filter).

Returns:

embedded documents of the current OdfPackageDocument matching the given media type

setOdfMediaType

protected void setOdfMediaType(OdfDocument.OdfMediaType odfMediaType)

Sets the media type of the OdfDocument

Parameters:

odfMediaType - media type to be set

getOdfMediaType

protected OdfDocument.OdfMediaType getOdfMediaType()

Gets the media type of the OdfDocument

getOfficeMetadata

public OdfOfficeMeta getOfficeMetadata()

Get the meta data feature instance of the current document

Returns:

the meta data feature instance which represent office:meta in the meta.xml

save

public void save(OutputStream out)
          throws Exception

Save the document to an OutputStream. Delegate to the root document and save possible embedded OdfDocuments.

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

If not, the OutputStream may not point to the input file! Otherwise this will result in unwanted behaviour and broken files.

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 stream to get the saved embedded document.

Parameters:

out - - the OutputStream to write the file to

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.

Overrides:

save in class OdfPackageDocument

Parameters:

file - - the file to save the document

Throws:

Exception - if the document could not be saved

close

public void close()

Close the document and release all temporary created data. After 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 AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class OdfSchemaDocument

getContentRoot

public OdfElement getContentRoot()
                          throws Exception

Get the content root of a document.

You may prefer to use the getContentRoot methods of subclasses of OdfDocument.

Returns:

the child element of office:body, e.g. office:text for text docs

Throws:

Exception - if the file DOM could not be created.

toString

public String toString()

Overrides:

toString in class Object

newImage

public String newImage(URI imageUri)

Insert an Image from the specified uri to the end of the OdfDocument.

Parameters:

imageUri - The URI of the image that will be added to the document, add image stream to the package, in the 'Pictures/' graphic directory with the same image file name as in the URI. If the imageURI is relative first the user.dir is taken to make it absolute.

Returns:

Returns the internal package path of the image, which was created based on the given URI.

getTableByName

public OdfTable getTableByName(String name)

Return an instance of table feature with the specific table name.

Parameters:

name - of the table being searched for.

Returns:

an instance of table feature with the specific table name.

getTableList

@Deprecated(since="It was not clear that this is searching recursively, especialy in OdfSpreadsheetDocuments")
public List<OdfTable> getTableList()

Deprecated.

Return a list of table features in this document. For general ODF documents it searches for them recursively through the document. For ODF documents, there is a getOdsTableList

Returns:

a list of table features in this document.

getTableList

public List<OdfTable> getTableList(boolean doRecursiveSearch)

Return a list of table features in this document. For general ODF documents it searches for tables recursively through the document.

Parameters:

doRecursiveSearch - In spreadsheet documents you do not need a recursive search.

Returns:

a list of table features in this document.

updateMetaData

public void updateMetaData()

Update document meta data in the ODF document. Following metadata data is being updated:

• The name of the person who last modified this document will be the Java user.name System property
• The date and time when the document was last modified using current data
• The number of times this document has been edited is incremented by 1
• The total time spent editing this document

TODO:This method will be moved to OdfMetadata class. see http://odftoolkit.org/bugzilla/show_bug.cgi?id=204

setLocale

public void setLocale(Locale locale)

Set a locale information.

The locale information will affect the language and country setting of the document. Thus the font settings, the spell checkings and etc will be affected.

Parameters:

locale - - an instance of Locale

getUnicodeGroup

public static OdfDocument.UnicodeGroup getUnicodeGroup(Locale locale)

Similar to OpenOffice.org, ODFDOM assumes that every Locale is related to one of the three Unicodes Groups, either CJK, CTL or Western.

Parameters:

locale - the UnicodeGroup is requested for

Returns:

the related UnicodeGroup

getLocale

public Locale getLocale(OdfDocument.UnicodeGroup unicodeGroup)

This method will return Locale, which presents the default language and country information settings in this document

ODF allows to set a Locale for each of the three UnicodeGroups. Therefore there might be three different Locale for the document.

Parameters:

unicodeGroup - - One of the three (CJK, CTL or Western).

Returns:

the Locale for the given UnicodeGroup

getFontNames

public Set<String> getFontNames()

This is a temporary solution to know about the fonts within the documents. Project client does not provide font information, therefore the 16 fonts are hard coded

addAnnotation

public void addAnnotation(String name,
                          OfficeAnnotationElement element)

getAnnotation

public OfficeAnnotationElement getAnnotation(String name)

removeAnnotation

public void removeAnnotation(String name)

getUniqueAnnotationName

public String getUniqueAnnotationName()

removeCachedView

protected void removeCachedView()

hasCollaboration

public Boolean hasCollaboration()

Returns:

TRUE if the document was created by CollabTextDocument and thereby supports user changes, otherwise FALSE