Usage

Configuration

The Configuration configures the behaviour of the Differ. It is a thread-safe object, of which every public method creates a copy.

Example initialisation:

Configuration configuration = new Configuration();

Provide a serializer

Each object in the graph needs serialization. By default the framework does only provide two kinds of serialization, which are Class serialization and serialization of nullvalues. Everything else must be implemented by the client. For example one could easily write a Serializer implementation that simply serializes each object by using it's toSstring() method like this:

Configuration configuration = new Configuration().useSerializer(new CheckableSerializer<Object>() {
		
	@Override
	public boolean applies(Object object) {
		return true;
	}

	@Override
	public String serialize(Object object) {
		return object.toString();
	}
});

The boolean applies(Object object) method, which is inherited from the Checkable interface, allows the serializer to decide whether the given object can or can not be serialized by the implementation, while the String serialize(T object) method does the actual work. The serializer is being called to serialize property values and keys of maps.

Note: In case the the Differdoes not find an appropriate Serializer it will throw a MissingSerializerException.

Provide a comparator

Java structures like Iterableand Map do not enforce order, though there are implementations or sub-interfaces which add this functionality. In order to provide consistent results when comparing for example two sets, it makes sense to enforce order on the objects contained in them. The same accounts for key/value pairs of maps, to enforce order on maps, the keys must be sorted. This means a provided CheckableComparator may be used to order any iterable or key set of a map.

The CheckableComparator extends the java.util.Comparator and the Checkable, through which an implementation can decide whether it can or cannot compare a given object which is an item of an iterable.

Note: The Differ will throw a MissingComparatorException in case it finds an iterable or a map which it can not sort.

The following example demonstrates how to implement a CheckableComparator which would order an iterable of a fictional User entity by it's identifier, assuming that neither the user nor the identifier could be null.

Configuration configuration = new Configuration().useComparator(new CheckableComparator<User>() {
	
	@Override
	public boolean applies(Object object) {
		return User.class.isInstance(object);
	}
	
	@Override
	public int compare(User o1, User o2) {
		return o1.getId().compareTo(o2.getId());
	}
});

Use natural ordering of an object

Sometimes you may have an iterable or map key set of objects, which already implement the java.lang.Comparable interface and it would be redundant to implement a CheckableComparator. The Configuration allows to specify classes which provide natural ordering and of which the natural order should be applied.

Let's assume you have a list of strings and want to specify that the Differ should use the natural ordering of the Stringclass to sort the list.

Configuration configuration = new Configuration().useNaturalOrderingFor(String.class);

Note: In case there is a natural ordering and a comparator provided for the same class, natural ordering takes precedence over a provided comparator.

Exclude properties

The configuration allows to exclude properties from being diffed. To exclude a property just provide the simple Java bean property name.

Assuming you have the following class:

public class User {
	private Integer id;
	private DateTime createdAt;

	// getters and setters omitted
	...
}

You could exclude the createdAt property from being diffed like this:

Configuration configuration = new Configuration().excludeProperty("createdAt");

Note: In case the property name occurs in different classes in the object graph, all occurrences are excluded. Currently there is no facility to exclude properties of specific classes.

Specify names of compared objects

The first two lines of each diff result show the header information with the name of the base and working objects prefixed with --- and +++ to indicate what has been added and what has been removed.

You can specify the name of the base and working objects through:

Configuration configuration = new Configuration
	.useBaseObjectName("BaseObject")
	.useWorkingObjectName("WorkingObject");

This config could produce this output:

--- BaseObject
+++ WorkingObject
@@ -1,1 +1,1 @@
-SomeDomainObject.someProperty='21'
+SomeDomainObject.someProperty='42'

Note: The default values are empty strings, which would produce this output:

--- 
+++ 
@@ -1,1 +1,1 @@
-SomeDomainObject.someProperty='21'
+SomeDomainObject.someProperty='42'

Differ

The Differ simply takes the above mentioned Configuration and applies the configuration when the diff method is being called. The Differ does not hold any mutable state and is thus thread-safe.

Example usage:

...

List<String> differences = new Differ(configuration).diff(base, working);

for (String diff : differences) {
	System.out.println(diff);
}