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.collections4.sequence;
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.collections4.comparators.sequence.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 * </p>
73 * <pre>
74 * import org.apache.commons.collections4.comparators.sequence.CommandVisitor;
75 *
76 * import java.util.Arrays;
77 * import java.util.ArrayList;
78 * import java.util.Iterator;
79 *
80 * public class ShowVisitor implements CommandVisitor {
81 *
82 * public ShowVisitor(Object[] sequence1) {
83 * v = new ArrayList();
84 * v.addAll(Arrays.asList(sequence1));
85 * index = 0;
86 * }
87 *
88 * public void visitInsertCommand(Object object) {
89 * v.insertElementAt(object, index++);
90 * display("insert", object);
91 * }
92 *
93 * public void visitKeepCommand(Object object) {
94 * ++index;
95 * display("keep ", object);
96 * }
97 *
98 * public void visitDeleteCommand(Object object) {
99 * v.remove(index);
100 * display("delete", object);
101 * }
102 *
103 * private void display(String commandName, Object object) {
104 * System.out.println(commandName + " " + object + " ->" + this);
105 * }
106 *
107 * public String toString() {
108 * StringBuffer buffer = new StringBuffer();
109 * for (Iterator iter = v.iterator(); iter.hasNext();) {
110 * buffer.append(' ').append(iter.next());
111 * }
112 * return buffer.toString();
113 * }
114 *
115 * private ArrayList v;
116 * private int index;
117 *
118 * }
119 * </pre>
120 *
121 * @since 4.0
122 */
123 public interface CommandVisitor<T> {
124
125 /**
126 * Method called when a delete command is encountered.
127 *
128 * @param object object to delete (this object comes from the first sequence)
129 */
130 void visitDeleteCommand(T object);
131
132 /**
133 * Method called when an insert command is encountered.
134 *
135 * @param object object to insert (this object comes from the second sequence)
136 */
137 void visitInsertCommand(T object);
138
139 /**
140 * Method called when a keep command is encountered.
141 *
142 * @param object object to keep (this object comes from the first sequence)
143 */
144 void visitKeepCommand(T object);
145
146 }