Package com.deltawalker.script

Interface Comparisons

public interface Comparisons
Creates comparisons and gives access to existing ones, including the comparison history - comparisons created earlier whose settings were saved so they can be run again. Obtained with App.getComparisons(). 

 const Comparison = Java.type('com.deltawalker.script.Comparison');

 const comps = App.getComparisons();
 const IN = App.getProperty('user.home') + '/test/samples';

 // Two-way folder comparison
 const folders = comps.create(Comparison.Type.FOLDER, [IN + '/f0', IN + '/f1'], null);

 // Three-way text comparison; the last path is the common base (Role.REF)
 const texts = comps.create(Comparison.Type.TEXT,
         [IN + '/q1.txt', IN + '/q2.txt', IN + '/q0.txt'], null);

 await Promise.all([folders.compare(), texts.compare()]);
Since:
2.0

  • Method Details

    • create

      Comparison create(Comparison.Type type, String[] paths, ComparisonListener listener)
      Creates a comparison of the specified Comparison.Type for the specified paths and opens it in a DeltaWalker window or view. The comparison itself runs when Comparison.compare() is called.

      The number of paths determines whether this is a two-way or a three-way comparison, and their order determines the Role of each resource:

      The returned object is a FolderComparison, TextComparison or ImageComparison, depending on type. Comparisons hold system resources, so close them with Comparison.close() when they are no longer needed. 

      
 const comp = App.getComparisons().create(Comparison.Type.TEXT,
         ['/path/to/file-a.txt', '/path/to/file-b.txt'], null);
 await comp.compare();
      Parameters:
      type - the type of comparison to create; cannot be null
      paths - the paths of the resources to compare, at most three. When null or empty, an empty comparison of the specified type is created.
      listener - an optional, legacy ComparisonListener to register on the new comparison; new scripts pass null and use await instead
      Returns:
      the newly created comparison; never null
      Throws:
      NullPointerException - if type is null
      IllegalArgumentException - if paths has more than 3 elements
      Since:
      2.0

    • createEx

      Comparison createEx(Comparison.Type type, UriInfo[] uriInfos, ComparisonListener listener)
      Like create(Comparison.Type, String[], ComparisonListener), but takes UriInfo objects instead of plain paths.

      A UriInfo carries additional information about a resource, such as the user name and password of a remote (S)FTP(S) server, or the character encoding and line ending of a text file. The order of the elements determines their Roles exactly as in create(). The following is based on folder-compare-remote.js, one of the samples that ship with DeltaWalker: 

      
 const Comparison = Java.type('com.deltawalker.script.Comparison');
 const UriInfo = Java.type('com.deltawalker.script.UriInfo');

 // A folder on an FTP server and a local folder
 const remote = new UriInfo('ftp://speedtest.tele2.net/');
 const local = new UriInfo(App.getProperty('user.home') + '/test/samples/f0');
 // For SFTP: new UriInfo('sftp://host', {username: 'user', password: 'pass'})

 const comp = App.getComparisons().createEx(Comparison.Type.FOLDER,
         [remote, local], null);
 await comp.compare();
      Parameters:
      type - the type of comparison to create; cannot be null
      uriInfos - the resources to compare. Only the first three elements are used; any further elements are ignored. When null or empty, an empty comparison of the specified type is created.
      listener - an optional, legacy ComparisonListener to register on the new comparison; new scripts pass null and use await instead
      Returns:
      the newly created comparison; never null
      Throws:
      NullPointerException - if type is null
      IllegalArgumentException - if a UriInfo has a property name that is not supported
      Since:
      2.0

    • createFromHistory

      Comparison createFromHistory(Object id, ComparisonListener listener)
      Creates a comparison from the comparison history: a comparison of the same type and over the same resources as the history entry with the specified ID. See get(Object) for how the ID is matched.
      Parameters:
      id - the ID - creation time or name - of the HistoryEntry to create the comparison from
      listener - an optional, legacy ComparisonListener to register on the new comparison; can be null
      Returns:
      the newly created comparison, or null if no history entry matches id
      Throws:
      NullPointerException - if id is null
      IllegalArgumentException - if id is an empty string
      Since:
      2.0

    • createFromReport

      Comparison createFromReport(String path, ComparisonListener listener)
      Opens a comparison from a ReportKind.JSON snapshot file, as created by FolderComparison.report(String, ReportKind, PatchFormat, Role[]). Only JSON snapshots are supported.
      Parameters:
      path - the full path of the snapshot file
      listener - ignored; pass null
      Returns:
      the comparison opened from the snapshot, or null if the snapshot could not be opened
      Since:
      2.1.0

    • get

      Comparison get(Object id)
      Looks up a comparison by its ID and opens it. The ID is either a creation time or a name:

      All comparisons known to DeltaWalker are searched, including history entries that are not currently open. The matching entry is opened as a comparison of the same type over the same resources, and that comparison is returned; it is not necessarily the same object as the one originally created. To enumerate the comparisons that are currently open, use getAll().

      Parameters:
      id - the ID - creation time or name - of the comparison to get
      Returns:
      the matching comparison, or null if no comparison matches id
      Throws:
      NullPointerException - if id is null
      IllegalArgumentException - if id is an empty string
      Since:
      2.0
      See Also:

    • getAll

      Comparison[] getAll()
      Returns all comparisons that are currently open in DeltaWalker, whether they were created by a script or in the UI.
      Returns:
      an array with zero or more comparisons; never null
      Since:
      2.0

    • getCount

      int getCount()
      Returns the number of comparisons known to DeltaWalker, including history entries that are not currently open. The result can therefore be larger than the length of getAll().
      Returns:
      the number of comparisons
      Since:
      2.0

    • getHistory

      HistoryEntry[] getHistory()
      Returns the comparison history: an entry for every comparison known to DeltaWalker, open or not.
      Returns:
      an array with zero or more history entries; never null
      See Also:

    • removeFromHistory

      boolean removeFromHistory(Object id)
      Removes the comparison with the specified ID from the comparison history. See get(Object) for how the ID is matched.
      Parameters:
      id - the ID - creation time or name - of the comparison to remove
      Returns:
      true if a comparison with the specified ID was found and removed, false otherwise
      Throws:
      NullPointerException - if id is null
      IllegalArgumentException - if id is an empty string
      Since:
      2.0
      See Also: