1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.text.diff;
18
19 /**
20 * This interface should be implemented by user object to walk
21 * through {@link EditScript EditScript} objects.
22 * <p>
23 * Users should implement this interface in order to walk through
24 * the {@link EditScript EditScript} object created by the comparison
25 * of two sequences. This is a direct application of the visitor
26 * design pattern. The {@link EditScript#visit EditScript.visit}
27 * method takes an object implementing this interface as an argument,
28 * it will perform the loop over all commands in the script and the
29 * proper methods of the user class will be called as the commands are
30 * encountered.
31 * </p>
32 * <p>
33 * The implementation of the user visitor class will depend on the
34 * need. Here are two examples.
35 * </p>
36 * <p>
37 * The first example is a visitor that build the longest common
38 * subsequence:
39 * </p>
40 * <pre>
41 * import org.apache.commons.text.diff.CommandVisitor;
42 *
43 * import java.util.ArrayList;
44 *
45 * public class LongestCommonSubSequence implements CommandVisitor {
46 *
47 * public LongestCommonSubSequence() {
48 * a = new ArrayList();
49 * }
50 *
51 * public void visitInsertCommand(Object object) {
52 * }
53 *
54 * public void visitKeepCommand(Object object) {
55 * a.add(object);
56 * }
57 *
58 * public void visitDeleteCommand(Object object) {
59 * }
60 *
61 * public Object[] getSubSequence() {
62 * return a.toArray();
63 * }
64 *
65 * private ArrayList a;
66 *
67 * }
68 * </pre>
69 * <p>
70 * The second example is a visitor that shows the commands and the way
71 * they transform the first sequence into the second one:
72 * <pre>
73 * import org.apache.commons.text.diff.CommandVisitor;
74 *
75 * import java.util.Arrays;
76 * import java.util.ArrayList;
77 * import java.util.Iterator;
78 *
79 * public class ShowVisitor implements CommandVisitor {
80 *
81 * public ShowVisitor(Object[] sequence1) {
82 * v = new ArrayList();
83 * v.addAll(Arrays.asList(sequence1));
84 * index = 0;
85 * }
86 *
87 * public void visitInsertCommand(Object object) {
88 * v.insertElementAt(object, index++);
89 * display("insert", object);
90 * }
91 *
92 * public void visitKeepCommand(Object object) {
93 * ++index;
94 * display("keep ", object);
95 * }
96 *
97 * public void visitDeleteCommand(Object object) {
98 * v.remove(index);
99 * display("delete", object);
100 * }
101 *
102 * private void display(String commandName, Object object) {
103 * System.out.println(commandName + " " + object + ": " + this);
104 * }
105 *
106 * public String toString() {
107 * StringBuffer buffer = new StringBuffer();
108 * for (Iterator iter = v.iterator(); iter.hasNext();) {
109 * buffer.append(' ').append(iter.next());
110 * }
111 * return buffer.toString();
112 * }
113 *
114 * private ArrayList v;
115 * private int index;
116 *
117 * }
118 * </pre>
119 *
120 * @param <T> object type
121 * @since 1.0
122 */
123 public interface CommandVisitor<T> {
124
125 /**
126 * Method called when an insert command is encountered.
127 *
128 * @param object object to insert (this object comes from the second sequence)
129 */
130 void visitInsertCommand(T object);
131
132 /**
133 * Method called when a keep command is encountered.
134 *
135 * @param object object to keep (this object comes from the first sequence)
136 */
137 void visitKeepCommand(T object);
138
139 /**
140 * Method called when a delete command is encountered.
141 *
142 * @param object object to delete (this object comes from the first sequence)
143 */
144 void visitDeleteCommand(T object);
145
146 }