    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.text.diff;
    018
    019/**
    020 * Walks through {@link EditScript EditScript} objects.
    021 * <p>
    022 * Users should implement this interface in order to walk through
    023 * the {@link EditScript EditScript} object created by the comparison
    024 * of two sequences. This is a direct application of the visitor
    025 * design pattern. The {@link EditScript#visit EditScript.visit}
    026 * method takes an object implementing this interface as an argument,
    027 * it will perform the loop over all commands in the script and the
    028 * proper methods of the user class will be called as the commands are
    029 * encountered.
    030 * </p>
    031 * <p>
    032 * The implementation of the user visitor class will depend on the
    033 * need. Here are two examples.
    034 * </p>
    035 * <p>
    036 * The first example is a visitor that build the longest common
    037 * subsequence:
    038 * </p>
    039 * <pre>
    040 * import org.apache.commons.text.diff.CommandVisitor;
    041 *
    042 * import java.util.ArrayList;
    043 *
    044 * public class LongestCommonSubSequence implements CommandVisitor {
    045 *
    046 *   public LongestCommonSubSequence() {
    047 *     a = new ArrayList();
    048 *   }
    049 *
    050 *   public void visitInsertCommand(Object object) {
    051 *   }
    052 *
    053 *   public void visitKeepCommand(Object object) {
    054 *     a.add(object);
    055 *   }
    056 *
    057 *   public void visitDeleteCommand(Object object) {
    058 *   }
    059 *
    060 *   public Object[] getSubSequence() {
    061 *     return a.toArray();
    062 *   }
    063 *
    064 *   private ArrayList a;
    065 *
    066 * }
    067 * </pre>
    068 * <p>
    069 * The second example is a visitor that shows the commands and the way
    070 * they transform the first sequence into the second one:
    071 * </p>
    072 * <pre>
    073 * import org.apache.commons.text.diff.CommandVisitor;
    074 *
    075 * import java.util.Arrays;
    076 * import java.util.ArrayList;
    077 * import java.util.Iterator;
    078 *
    079 * public class ShowVisitor implements CommandVisitor {
    080 *
    081 *   public ShowVisitor(Object[] sequence1) {
    082 *     v = new ArrayList();
    083 *     v.addAll(Arrays.asList(sequence1));
    084 *     index = 0;
    085 *   }
    086 *
    087 *   public void visitInsertCommand(Object object) {
    088 *     v.insertElementAt(object, index++);
    089 *     display("insert", object);
    090 *   }
    091 *
    092 *   public void visitKeepCommand(Object object) {
    093 *     ++index;
    094 *     display("keep  ", object);
    095 *   }
    096 *
    097 *   public void visitDeleteCommand(Object object) {
    098 *     v.remove(index);
    099 *     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 */
    123public 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}