org.openoffice.xmerge package

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 registered 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.