
package nxm.ucl.inc;

/** Defines an interface to a <code>diff</code> tool that will compare two files
    and indicate the differences between them.

    @author  J. Czechowski IV
    @version $Id: DiffTool.java,v 1.2 2004/12/21 17:06:19 jxc Exp $
    @since   NeXtMidas 1.9.2
 */
public interface DiffTool {
  
  /** Creates a new DiffTool instance for the given mime type.
   
      @param mimeType The mime type of the input files.
   
      @return A new diff tool that will compare two files of the given mime
              type. If the given mime type is not supported then
              <code>null</code> will be returned.
   */
  public DiffTool getDiffTool(String mimeType);
  
  /** Compares the two files.
   
      @param oldFile The old file.
      @param newFile The new file.
   
      @return The differences between the two files.
   
      @throws IllegalArgumentException If either file is null.
   */
  public FileDiff[] getDiffs(String[] oldFile, String[] newFile)
  throws IllegalArgumentException;
  
  
  /** Specifies the differences between the two files. */
  public interface FileDiff {
    /** Returns the start location of the change in the old file. If this is
        an insertion then the line number reflects the first line in the
        old file that follows the insertion. If this is a removal then
        this is the line number of the first line removed.
     
        @return The (<b>zero based</b>) line number the change begins on in
                the old file.
     
        @see #getNewFileStart()
     */
    public int getOldFileStart();
    
    /** Returns the start location of the change in the new file.
     
        @return The line number the change begins on in the new file.
     
        @see #getOldFileStart()
     */
    public int getNewFileStart();
    
    /** Gets the number of lines inserted going from the old file
        to the new file.
     
        @return The number of lines inserted.
     */
    public int getLinesInserted();
    
    /** Gets the number of lines removed going from the old file
        to the new file.
     
        @return The number of lines inserted.
     */
    public int getLinesRemoved();
  }
}
