1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2<!-- 3#************************************************************** 4# 5# Licensed to the Apache Software Foundation (ASF) under one 6# or more contributor license agreements. See the NOTICE file 7# distributed with this work for additional information 8# regarding copyright ownership. The ASF licenses this file 9# to you under the Apache License, Version 2.0 (the 10# "License"); you may not use this file except in compliance 11# with the License. You may obtain a copy of the License at 12# 13# http://www.apache.org/licenses/LICENSE-2.0 14# 15# Unless required by applicable law or agreed to in writing, 16# software distributed under the License is distributed on an 17# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 18# KIND, either express or implied. See the License for the 19# specific language governing permissions and limitations 20# under the License. 21# 22#************************************************************** 23 --> 24<html> 25<head> 26<title>org.openoffice.xmerge package</title> 27</head> 28 29<body bgcolor="white"> 30 31<p>Provides interfaces for converting between two <code>Document</code> 32formats, and supports a "merge" interface for merging back 33changes from a "lossy" format back into a rich format.</p> 34 35<p>The {@link org.openoffice.xmerge.Convert 36Convert} object encapsulates the conversion of one format to/from another 37format. The user requests a <code>Convert</code> object via the 38<code>ConverterFactory</code>.</p> 39 40<p>The <code>Convert</code> class encapsulates a specific plug-in. 41A plug-in can support deserialization (convert from "Device" 42to "Office") and/or serialization (convert from 43"Office" to "Device"). If a plug-in supports 44both deserialization and serialization, then it can also support 45"merge".</p> 46 47<p>To support conversions where a single input <code>Document</code> can 48create multiple output <code>Document</code> objects, data is passed in 49and out of the conversion functions via a <code>ConvertData</code> object. 50This <code>ConvertData</code> can contain one or more <code>Document</code> 51objects. It is assumed that the client will know when to pass multiple 52files into a specific plug-in, and that the plug-in will know how to 53handle the multiple files.</p> 54 55<p>Merging is useful when converting from a rich <code>Document</code> 56format to a more lossy format. Then the user may modify the 57<code>Document</code> in the lossy format, and "merge" those 58changes back into the original "rich" <code>Document</code>. 59Each merge implementation provides a <code>ConverterCapabilities</code> 60implementation so that the merge logic knows what changes from the 61"lossy" format to merge into the original "rich" 62<code>Document</code>.</p> 63 64<p>Each plug-in must be registed via the singleton ConverterInfoMgr 65object via its {@link 66org.openoffice.xmerge.util.registry.ConverterInfoMgr#addPlugIn 67addPlugIn} method.</p> 68 69<h2>Providing implementations</h2> 70 71<p>The plug-in implementation must include the <code>getDeviceDocument</code> 72and <code>getOfficeDocument</code> methods. These functions need to return 73the appropriate type of <code>Document</code> for the plug-in. It may be 74necessary to create a new implementation of the <code>Document</code> 75interface if one does not exist that meets the needs of the plug-in.</p> 76 77<p>Currently, base implementations for working with StarWriter XML 78<code>Document</code> objects are available via the 79<a href="converter/xml/sxc/package-summary.html#package_description"> 80org.openoffice.xmerge.xml.sxw</a> 81package, and StarCalc XML <code>Document</code> objects via the 82<a href="converter/xml/sxw/package-summary.html#package_description"> 83org.openoffice.xmerge.xml.sxc</a> 84package.</p> 85 86<h2>TODO/IDEAS list</h2> 87 88<p><ol> 89<li>An idea is to combine the <code>ConvertData</code> and the 90 <code>Convert</code> classes, so that a <code>ConvertData</code> 91 knows what it can convert into and whether or not it can merge. 92 Then a user would call convert/merge methods on the 93 <code>ConvertData</code> class, which returns a 94 <code>ConvertData</code> object that likewise knows what it can 95 convert/merge into.</li> 96<li><code>DocumentSerialize</code> constructors and the 97 <code>DocumentDeserializer.deserializer</code> method could pass 98 in a <code>ConvertData</code> object rather than assuming 99 a single <code>Document</code> will represent a "rich" 100 <code>Document</code>.</li> 101<li>May need to add a <code>PluginFactory.setProperties</code> 102 method for adding properties specific to each converter.</li> 103</ol></p> 104 105</body> 106</html> 107 108