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 {@link org.openoffice.xmerge.Convert 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 registed via the singleton ConverterInfoMgr object via its {@link org.openoffice.xmerge.util.registry.ConverterInfoMgr#addPlugIn 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.