Package org.openoffice.xmerge

Provides interfaces for converting between two Document formats, and supports a "merge" interface for merging back changes from a "lossy" format back into a rich format. More...

Packages
package	merger
	The DiffAlgorithm and MergeAlgorithm are used to provide the merge capabilities of this project.
package	test
package	util
	Provides general purpose utilities.

Classes
class	Convert
	The Convert class manages a conversion from one mime-type to another. More...
class	ConvertData
	ConvertData is used as a container for passing Document objects in and out of the Convert class. More...
interface	ConverterCapabilities
	A ConverterCapabilities object is used by DocumentMerger implementations. More...
class	ConverterFactory
	Factory that provides access to Convert objects, which are used to do a conversion. More...
class	ConvertException
	This Exception is thrown by convert algorithms. More...
interface	Document
	A Document represents any Document to be converted and the resulting Document from any conversion. More...
interface	DocumentDeserializer
	A DocumentDeserializer represents a converter that converts "Device" Document objects into the "Office" Document format. More...
interface	DocumentDeserializer2
	A DocumentDeserializer represents a converter that converts "Device" Document objects into the "Office" Document format. More...
interface	DocumentDeserializerFactory
	A DocumentDeserializer object is used to convert from the "Device" Document format to the "Office" Document format. More...
interface	DocumentMerger
	A DocumentMerger can merge changes from a modified "Device" Document to the assigned original "Office" Document. More...
interface	DocumentMergerFactory
	All plug-in implementations of the PluginFactory interface that also support merging must also implement this interface. More...
interface	DocumentSerializer
	A DocumentSerializer represents a converter that converts a "Office" Document to a "Device" Document format. More...
interface	DocumentSerializer2
	A DocumentSerializer2 represents a converter that converts a "Office" Document to a "Device" Document format. More...
interface	DocumentSerializerFactory
	A DocumentSerializer object is used to convert from the "Office" Document format to the "Device" Document format. More...
class	MergeException
	This Exception is thrown by merge algorithms. More...
class	PluginFactory
	A PluginFactory encapsulates the conversions from one Document format to another. More...
class	Version
	This class provides a quick utility to check the version of the jar file. More...

Detailed Description

Provides interfaces for converting between two Document formats, and supports a "merge" interface for merging back changes from a "lossy" format back into a rich format.

The Convert object encapsulates the conversion of one format to/from another format. The user requests a Convert object via the ConverterFactory.

The Convert class encapsulates a specific plug-in. A plug-in can support deserialization (convert from "Device" to "Office") and/or serialization (convert from "Office" to "Device"). If a plug-in supports both deserialization and serialization, then it can also support "merge".

To support conversions where a single input Document can create multiple output Document objects, data is passed in and out of the conversion functions via a ConvertData" object. This ConvertData can contain one or more Document objects. It is assumed that the client will know when to pass multiple files into a specific plug-in, and that the plug-in will know how to handle the multiple files.

Merging is useful when converting from a rich Document format to a more lossy format. Then the user may modify the Document in the lossy format, and "merge" those changes back into the original "rich" Document. Each merge implementation provides a ConverterCapabilities implementation so that the merge logic knows what changes from the "lossy" format to merge into the original "rich" Document.

Each plug-in must be registered via the singleton ConverterInfoMgr object via its addPlugIn method.

Providing implementations

The plug-in implementation must include the getDeviceDocument and getOfficeDocument methods. These functions need to return the appropriate type of Document for the plug-in. It may be necessary to create a new implementation of the Document interface if one does not exist that meets the needs of the plug-in.

Currently, base implementations for working with StarWriter XML Document objects are available via the org.openoffice.xmerge.xml.sxw package, and StarCalc XML Document objects via the org.openoffice.xmerge.xml.sxc package.

TODO/IDEAS list

1. An idea is to combine the ConvertData and the Convert classes, so that a ConvertData knows what it can convert into and whether or not it can merge. Then a user would call convert/merge methods on the ConvertData class, which returns a ConvertData object that likewise knows what it can convert/merge into.
2. DocumentSerialize constructors and the DocumentDeserializer.deserializer method could pass in a ConvertData object rather than assuming a single Document will represent a "rich" Document.
3. May need to add a PluginFactory.setProperties method for adding properties specific to each converter.