README.md

compare-utils

Comparing of Java Collections and Objects made easy.

Minimalistic library written in core Java with no other dependencies.

It provides easy way to compare Collections and Objects of same or different class when Java's equals functions and Java's Comparators don't suffice.

Collections compare result is presented with clear separation of added, removed, updated and unchanged items.

See Usage and Javadoc.

Add to your project

Maven

<dependency>
  <groupId>io.github.nejckorasa</groupId>
  <artifactId>compare-utils</artifactId>
  <version>1.1.0</version>
</dependency>

Gradle

compile 'io.github.nejckorasa:compare-utils:1.1.0'

Usage

At first glance it might seem that this is no different from using Java's own Comparator and even Java's equals functions. For some use cases it is indeed easier to use Comparator, and you should do so!

A few examples where this library is useful:

• Compare collections of different object classes

  • Specify keyExtractor and your own equals function
  • Instead of writing equals function, you can compare objects by comparing only some of its fields

• Compare objects (of same or different class) by comparing only some of its fields

  • Define field extractors

Example

Given some classes and 2 collections:

static SomeClass {
    long id;
    int firstProperty;
    String secondProperty;
}

static OtherClass {
    long id;
    int propertyOne;
    String propertyTwo;
}

Compare collections of different classes by only comparing 2 of their fields and matching by id:

List<SomeClass> firstList;
List<OtherClass> secondList;

CollectionCmp
    .of(firstList, secondList, o1 -> o1.getId(), o2 -> o2.getId())
    .compare(
        EqualityPair.of(o1 -> o1.firstProperty(), o2 -> o2.propertyOne()),
        EqualityPair.of(o1 -> o1.secondProperty(), o2 -> o2.propertyTwo()));

Compare objects of different classes by only comparing 2 of their fields:

SomeClass first;
OtherClass second;

ObjectCmp.equals(
        first,
        second,
        EqPair.of((o1 -> o1.firstProperty(), o2 -> o2.propertyOne()),
        EqPair.of(o1 -> o1.secondProperty(), o2 -> o2.propertyTwo()));

Find more examples in tests.

Collections compare

Basics

It provides comparing and finding differences between two collections (base and working). Items in collections can be of same or different classes. Two steps are important to understand how comparison is made and how differences are found:

1. Matching

   First, items from both collections are matched together by their keys. Provided keyExtractor functions are used to extract the keys. When 2 items match they form a Pair.

2. Comparing

   Provided equalsFunction, equalities or equalityPairs are used to compare the pairs.

Matching

Matching is computed using keyExtractor functions, for example i -> i.getId():

CollectionCmp
        .of(baseList, workingList, i -> i.getId())
        .compare();

or when comparing collections of different item classes:

CollectionCmp
        .of(baseList, workingList, b -> b.getId(), w -> w.getId()) // keyExtractor functions for base and working items
        .compare(); // keyExtractor functions for base and working items

keyExtractors are not optional and must always be provided.

Comparing

Comparing is performed on items that are matched together (they form a Pair). This is done by equals function which can be defined in a few different ways, using compare(...) function:

equalsFunction

CollectionCmp
        .of(baseList, workingList, i -> i.getId())
        .compare((i1, i2) -> i1.getName().equals(i2.getName()));

equalities or equality pairs

CollectionCmp
        .of(baseList, workingList, i -> i.getId())
        .compare(
          item -> item.getName(), 
          item -> item.getCode(), 
          item -> item.getDescription());

In example above, items are considered equal when name, code and description fields are equal. Similarly with collections of different classes, equality pairs are used:

CollectionCmp
        .of(baseList, workingList, b -> b.getId(), w -> w.getId())
        .compare(
            EqPair.of(b -> b.getName(), w -> w.getData().getName()),
            EqPair.of(b -> b.getCode(), w -> w.getData().getCode()));

Now, items are considered equal when name and code fields are equal. Because base and working items are not of same class, fields may exist on different paths.

equalsFunction is optional, by default Objects.equals() is used to compare matched items.

Result

Compare result of collections is presented with clear separation of added, removed, updated and unchanged items. Result object has a few useful functions to help you analyze result data:

var compareResult = CollectionCmp
        .of(baseList, workingList, i -> i.getId())
        .compare(i -> i.getName());

boolean hasChanges = compareResult.hasChanges();
int changesCount = compareResult.getChangesCount();

boolean hasDifferences = compareResult.hasDifferences();
int differentCount = compareResult.getDifferentCount();

compareResult.getAll();
compareResult.getAdded();
compareResult.getUdpated();

// changed are all items that were added, removed or updated
compareResult.getChanged();
compareResult.getUncanged();

// stream through changed, unchanged, added, different items ...
compareResult.streamChanged()

All result data is provided in Pairs, containing matched base and working item as well as difference type:

CmpPair<B, W> pair = ...

B base = pair.getBase();
W working = pair.getWorking();

Diff diff = pair.getDiff(); // UNCHANGED, UPDATED, ADDED, REMOVED
Serializable key = pair.getKey(); // key by which items are matched together

Partitioning

Matching must be a injective function (in both ways) == there must be at most one item with the same key in each collection. If that is not true, collection cannot be partitioned and collections compare result might be incorrect.

You can check if collection can be partitioned using:

boolean canPartition = CollectionCmpPartitioner.canPartition(collection, keyExtractor)

Objects compare

Objects are compared using same features as comparing collections above, for example:

// check if objects are equal based on it's name, code and description
boolean equals = ObjectCmp.equals(
    object1, 
    object2, 
    o -> o.getName(), o -> o.getCode(), o -> o.getDescription());

Contributing

Pull requests are welcome, Show your ❤ with a ★