1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 package org.openoffice.xmerge; 25 26 /** 27 * <p>A <code>DocumentMerger</code> can merge changes from a modified 28 * "Device" <code>Document</code> to the assigned original 29 * "Office" <code>Document</code>.</p> 30 * 31 * <p>Merge is useful when an <code>OfficeDocument</code> 32 * is converted to a "Device" <code>Document</code> format, 33 * and the "Device" <code>Document</code> version is modified. 34 * Those changes can be merged back into the original 35 * <code>OfficeDocument</code> with the merger. The merger is capable 36 * of doing this even if the "Device" format is lossy in 37 * comparison to the <code>OfficeDocument</code> format.</p> 38 * 39 * <p>The <code>ConverterCapabilities</code> object is what the 40 * DocumentMerger utilizes to know how the "Office" 41 * <code>Document</code> tags are supported in the "Device" 42 * format.</p> 43 * 44 * <p>The <code>DocumentMerger</code> object is created by a 45 * the <code>DocumentMergerFactory</code> {@link 46 * org.openoffice.xmerge.DocumentMergerFactory#createDocumentMerger 47 * createDocumenMerger} method. When it is constructed, the 48 * "Original Office" <code>Document</code> object is 49 * passed in to be used as input.</p> 50 * 51 * @author Herbie Ong 52 * @see org.openoffice.xmerge.PluginFactory 53 * @see org.openoffice.xmerge.DocumentMergerFactory 54 * @see org.openoffice.xmerge.ConverterCapabilities 55 */ 56 public interface DocumentMerger { 57 58 /** 59 * <p>This method will find the changes that had happened 60 * in the <code>modifiedDoc</code> <code>Document</code> 61 * object given the designated original <code>Document</code>.</p> 62 * 63 * <p>Note that this process may need the knowledge of the 64 * conversion process since some conversion process are lossy. 65 * Items/Data that are lost during the conversion process are not 66 * classified as changes. The main target of this method 67 * is to apply the changes done in <code>modifiedDoc</code> 68 * into the assigned original <code>Document</code> object, thus 69 * it also will try to preserve items that were originally in 70 * the original <code>Document</code>, but never got transferred 71 * during the 72 * {@link org.openoffice.xmerge.DocumentSerializer#serialize 73 * serialize} process/method call. After this method call, the 74 * original <code>Document</code> object will contain the changes 75 * applied.</p> 76 * 77 * <p>This method may or may not be thread-safe. 78 * Also, it is expected that the user uses only one instance 79 * of a <code>DocumentMerger</code> object per merge process. 80 * Create another <code>DocumentMerger</code> object for another 81 * merge process.</p> 82 * 83 * @param modifiedDoc device <code>Document</code> object. 84 * 85 * @throws MergeException If any merge error occurs. 86 */ merge(Document modifiedDoc)87 public void merge(Document modifiedDoc) throws MergeException; 88 } 89 90