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.merger; 25 26 /** 27 * This is an interface used by the {@link 28 * org.openoffice.xmerge.merger.DiffAlgorithm 29 * DiffAlgorithm} and {@link 30 * org.openoffice.xmerge.merger.MergeAlgorithm 31 * MergeAlgorithm} to access a <code>Document</code>. 32 * 33 * @author smak 34 */ 35 public interface Iterator { 36 37 38 /** 39 * Move to next element in the sequence. 40 * 41 * @return The <code>Object</code> of the next element in the sequence. 42 * If there is no next element, then return null. 43 */ next()44 public Object next(); 45 46 47 /** 48 * Move to previous element in the sequence. 49 * 50 * @return The <code>Object</code> of the previous element in the sequence. 51 * If there is no previous element, then return null. 52 */ previous()53 public Object previous(); 54 55 56 /** 57 * Move to the beginning of the sequence. 58 * 59 * @return The <code>Object</code> of the first element in the sequence. 60 * If it is empty, then return null. 61 */ start()62 public Object start(); 63 64 65 /** 66 * Move to the end of the sequence. 67 * 68 * @return The <code>Object</code> of the last element in the sequence. 69 * If it is empty, then return null. 70 */ end()71 public Object end(); 72 73 74 /** 75 * Return the current element <code>Object</code> content. 76 * 77 * @return The <code>Object</code> at current position. 78 */ currentElement()79 public Object currentElement(); 80 81 82 /** 83 * Return the total element count in the sequence. 84 * 85 * @return The total element count. 86 */ elementCount()87 public int elementCount(); 88 89 90 /** 91 * A method to allow the difference algorithm to test whether the 92 * <code>obj1</code> and <code>obj2</code> in the 93 * <code>Iterator</code> are considered equal. As not every 94 * <code>Object</code> in the <code>Iterator</code> can implement its 95 * own equal method, with this equivalent method, we can allow 96 * flexibility for the <code>Iterator</code> to choose a custom way 97 * to compare two objects. Two objects can even be compared based on 98 * the position in the <code>Iterator</code> rather than by 99 * the content via this option. 100 * 101 * @param obj1 The first <code>Object</code>. 102 * @param obj2 The second <code>Object</code>. 103 * 104 * @return true if equal, false otherwise. 105 */ equivalent(Object obj1, Object obj2)106 public boolean equivalent(Object obj1, Object obj2); 107 108 109 /** 110 * <p>A method to force the <code>Iterator</code> to transverse the tree 111 * again to refresh the content.</p> 112 * 113 * <p>It is used mainly for <code>Iterator</code> objects which take a snap 114 * shot instead of dynamically transversing the tree. The current 115 * position will be set to the beginning.</p> 116 */ refresh()117 public void refresh(); 118 } 119 120