Package com.deltawalker.script

Interface FolderComparison

All Superinterfaces:
Comparison, HistoryEntry
public interface FolderComparison extends Comparison
A Comparison of folder hierarchies. Its results are a tree of DeltaNodes, one per file or folder, each holding the Resource found at every Role. 

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

 const TEST_DIR = App.getProperty('user.home') + '/test';
 const IN = TEST_DIR + '/samples';
 const comp = App.getComparisons().create(Comparison.Type.FOLDER,
         [IN + '/f0', IN + '/f1'], null);
 await comp.compare();

 const nodes = comp.getAllDeltas();
 for (let i = 0; i < nodes.length; i++) {
     const node = nodes[i];
     if (!node.isSame()) {
         const res = node.resource(Role.REF) || node.resource(Role.ONE);
         console.log(res.getPath() + ' differs');
     }
 }
 await comp.report(TEST_DIR + '/folder-report.html', ReportKind.HTML, null, null);
Since:
2.0

  • Method Details

    • deleteResource

      void deleteResource(DeltaNode[] deltas, Role[] roles, SyncProgressListener spm) throws IOException
      Deletes the Resources with the specified Roles from the specified DeltaNodes. This deletes files and folders on disk.

      Each deletion triggers a partial re-comparison, which can be expensive. When deleting several resources, gather them and pass them in a single call rather than calling this method repeatedly.

      When the last resource of a node is deleted, the node itself is removed. Nodes that have no resource at a specified role are left unchanged for that role. 

      
 // Delete the Role.ONE copy of a file
 comp.deleteResource([node], [Role.ONE], null);
      Parameters:
      deltas - the nodes to delete resources from; cannot be null or empty
      roles - the roles of the resources to delete; cannot be null or empty, and must all be roles of this comparison
      spm - an optional SyncProgressListener to track the progress of this operation and to cancel it; can be null
      Throws:
      NullPointerException - if deltas or roles is null
      IllegalArgumentException - if deltas or roles is empty, or if a role is not a role of this comparison, for instance Role.TWO in a two-way comparison
      IOException - if deleting fails
      Since:
      2.0

    • getAllDeltas

      DeltaNode[] getAllDeltas()
      Returns all nodes of this comparison that are not excluded by filters, whether their resources are identical or different. Use Delta.isSame() and the other is...() methods of Delta to tell them apart.
      Returns:
      an array of this comparison's DeltaNodes
      Since:
      2.0

    • getDeltaCount

      int getDeltaCount()
      Returns the number of nodes in this comparison, the same as the length of getAllDeltas().
      Returns:
      the number of nodes
      Since:
      2.0

    • getRootDelta

      DeltaNode getRootDelta()
      Returns the root DeltaNode of this comparison. The root reports a difference when any node below it differs.
      Returns:
      the root node of this comparison
      Since:
      2.0

    • recompare

      void recompare(DeltaNode[] nodes)
      Re-compares the specified nodes, updating their results as well as the results of the nodes that depend on them, such as their parent folders.
      Parameters:
      nodes - the nodes to re-compare; cannot be null. When empty, this method does nothing.
      Throws:
      NullPointerException - if nodes is null
      Since:
      2.0

    • report

      ScriptOperation report(String pathname, ReportKind kind, PatchFormat format, Role[] roles)
      Writes a report of the results of this comparison to a file, and returns an operation that settles when the report has been written. 
      
 await comp.report('/path/to/report.html', ReportKind.HTML, null, null);

 // A JSON snapshot of the Role.REF hierarchy
 await comp.report('/path/to/snapshot.json', ReportKind.JSON, null, [Role.REF]);

      Patch reports (ReportKind.PATCH) are not implemented for folder comparisons: no file is written and the returned operation resolves immediately.

      Parameters:
      pathname - the path of the report file; cannot be null or empty
      kind - the kind of report; cannot be null. See ReportKind.
      format - the format of a patch report; required only when kind is ReportKind.PATCH, otherwise can be null. See PatchFormat.
      roles - the roles of the folder hierarchies to include in a snapshot; required, and cannot be empty, only when kind is ReportKind.JSON. Can be null for other kinds of reports.
      Returns:
      an operation that resolves when the report has been written
      Throws:
      NullPointerException - if pathname is null or empty, if kind is null, if format is missing for a patch report, or if roles is missing or empty for a JSON snapshot
      Since:
      2.1.0
      See Also:

    • reportEx

      ScriptOperation reportEx(UriInfo uriInfo, ReportKind kind, PatchFormat format, ReportLink link, Role[] roles)
      Like report(String, ReportKind, PatchFormat, Role[]), but takes a UriInfo for the report file, so that, for example, a remote location, a user name and password, a character encoding or a line ending can be specified, and can create linked reports. When the UriInfo specifies no character encoding, UTF-8 is used.
      Parameters:
      uriInfo - the location of the report file; cannot be null and must have a non-empty URI
      kind - the kind of report; cannot be null. See ReportKind.
      format - the format of a patch report; required only when kind is ReportKind.PATCH, otherwise can be null. See PatchFormat.
      link - for HTML reports, which linked file comparison reports to create; can be null. See ReportLink.
      roles - the roles of the folder hierarchies to include in a snapshot; required, and cannot be empty, only when kind is ReportKind.JSON. Can be null for other kinds of reports.
      Returns:
      an operation that resolves when the report has been written
      Throws:
      NullPointerException - if uriInfo is null or has an empty URI, if kind is null, if format is missing for a patch report, or if roles is missing or empty for a JSON snapshot
      Since:
      2.0.02

    • sort

      void sort(Role role, SortBy sortBy, SortDirection sortOrder)
      Sorts the folder hierarchy with the specified role by the specified column and direction.
      Parameters:
      role - the Role of the folder hierarchy to sort
      sortBy - the column to sort by
      sortOrder - the direction to sort in
      Since:
      2.0

    • sync

      ScriptOperation sync(SyncOp syncOp, DeltaNode[] nodes, Role src, Role dst, SyncProgressListener spl) throws IOException
      Applies the specified SyncOp to the specified DeltaNodes, from the source role to the destination role, and returns an operation that settles when synchronization completes. This changes files and folders on disk. 
      
 const SyncOp = Java.type('com.deltawalker.script.SyncOp');

 // Two-way: copy the selected nodes from Role.ONE to Role.REF
 await comp.sync(SyncOp.COPY, nodes, Role.ONE, Role.REF, null);

 // Three-way: bring non-conflicting changes into Role.REF; no source role
 await comp.sync(SyncOp.SYNC, comp.getAllDeltas(), null, Role.REF, null);
      Parameters:
      syncOp - the operation to perform; cannot be null
      nodes - the nodes to synchronize; cannot be null. When empty, nothing is done and the returned operation is already resolved.
      src - the source role. Cannot be the same as dst. Pass null for SyncOp.SYNC, which takes its sources from both Role.ONE and Role.TWO.
      dst - the destination role; cannot be null
      spl - an optional SyncProgressListener to track the progress of this operation and to cancel it; can be null
      Returns:
      an operation that resolves when synchronization completes
      Throws:
      IOException - if the synchronization fails
      NullPointerException - if syncOp, nodes or dst is null
      IllegalArgumentException - if src and dst are the same, if Role.TWO is used in a two-way comparison, or if SyncOp.SYNC is used in a two-way comparison
      Since:
      2.0