| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <!-- |
| #************************************************************** |
| # |
| # Licensed to the Apache Software Foundation (ASF) under one |
| # or more contributor license agreements. See the NOTICE file |
| # distributed with this work for additional information |
| # regarding copyright ownership. The ASF licenses this file |
| # to you under the Apache License, Version 2.0 (the |
| # "License"); you may not use this file except in compliance |
| # with the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, |
| # software distributed under the License is distributed on an |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| # KIND, either express or implied. See the License for the |
| # specific language governing permissions and limitations |
| # under the License. |
| # |
| #************************************************************** |
| --> |
| <html> |
| <head> |
| <title>org.openoffice.xmerge package</title> |
| </head> |
| |
| <body bgcolor="white"> |
| |
| <p>Provides interfaces for converting between two <code>Document</code> |
| formats, and supports a "merge" interface for merging back |
| changes from a "lossy" format back into a rich format.</p> |
| |
| <p>The {@link org.openoffice.xmerge.Convert |
| Convert} object encapsulates the conversion of one format to/from another |
| format. The user requests a <code>Convert</code> object via the |
| <code>ConverterFactory</code>.</p> |
| |
| <p>The <code>Convert</code> 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".</p> |
| |
| <p>To support conversions where a single input <code>Document</code> can |
| create multiple output <code>Document</code> objects, data is passed in |
| and out of the conversion functions via a <code>ConvertData</code> object. |
| This <code>ConvertData</code> can contain one or more <code>Document</code> |
| 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.</p> |
| |
| <p>Merging is useful when converting from a rich <code>Document</code> |
| format to a more lossy format. Then the user may modify the |
| <code>Document</code> in the lossy format, and "merge" those |
| changes back into the original "rich" <code>Document</code>. |
| Each merge implementation provides a <code>ConverterCapabilities</code> |
| implementation so that the merge logic knows what changes from the |
| "lossy" format to merge into the original "rich" |
| <code>Document</code>.</p> |
| |
| <p>Each plug-in must be registed via the singleton ConverterInfoMgr |
| object via its {@link |
| org.openoffice.xmerge.util.registry.ConverterInfoMgr#addPlugIn |
| addPlugIn} method.</p> |
| |
| <h2>Providing implementations</h2> |
| |
| <p>The plug-in implementation must include the <code>getDeviceDocument</code> |
| and <code>getOfficeDocument</code> methods. These functions need to return |
| the appropriate type of <code>Document</code> for the plug-in. It may be |
| necessary to create a new implementation of the <code>Document</code> |
| interface if one does not exist that meets the needs of the plug-in.</p> |
| |
| <p>Currently, base implementations for working with StarWriter XML |
| <code>Document</code> objects are available via the |
| <a href="converter/xml/sxc/package-summary.html#package_description"> |
| org.openoffice.xmerge.xml.sxw</a> |
| package, and StarCalc XML <code>Document</code> objects via the |
| <a href="converter/xml/sxw/package-summary.html#package_description"> |
| org.openoffice.xmerge.xml.sxc</a> |
| package.</p> |
| |
| <h2>TODO/IDEAS list</h2> |
| |
| <p><ol> |
| <li>An idea is to combine the <code>ConvertData</code> and the |
| <code>Convert</code> classes, so that a <code>ConvertData</code> |
| knows what it can convert into and whether or not it can merge. |
| Then a user would call convert/merge methods on the |
| <code>ConvertData</code> class, which returns a |
| <code>ConvertData</code> object that likewise knows what it can |
| convert/merge into.</li> |
| <li><code>DocumentSerialize</code> constructors and the |
| <code>DocumentDeserializer.deserializer</code> method could pass |
| in a <code>ConvertData</code> object rather than assuming |
| a single <code>Document</code> will represent a "rich" |
| <code>Document</code>.</li> |
| <li>May need to add a <code>PluginFactory.setProperties</code> |
| method for adding properties specific to each converter.</li> |
| </ol></p> |
| |
| </body> |
| </html> |
| |
