Package uk.megaslice.delta

Class Delta<T,K>

java.lang.Object

uk.megaslice.delta.Delta<T,K>

Type Parameters:

T - the type of dataset items

K - the type of the items' natural keys

public final class Delta<T,K>
extends Object

Represents changes to a dataset in terms of insert, update and delete operations. Deltas can be created using the diff method.

Method Summary

Modifier and Type	Method	Description
Collection<T>	apply(Iterable<T> items, NaturalKey<T,K> naturalKey)	Applies this delta's inserts, updates and deletes to another dataset.
Map<K,T>	apply(Map<K,T> items)	Applies this delta's inserts, updates and deletes to another dataset.
Delta<T,K>	combine(Delta<T,K> other)	Combines this delta with another delta, using a default item equivalence function.
Delta<T,K>	combine(Delta<T,K> other, Equivalence<T> equivalence)	Combines this delta with another delta.
<U> Delta<T,K>	combine(Delta<T,K> other, Essence<T,U> essence)	Combines this delta with another delta, using an Essence function to distill items for comparison.
Collection<T>	deletedItems()	Returns the deleted items of this delta.
Collection<Operation<T>>	deletes()	Returns the delete operations of this delta.
static <T,K> Delta<T,K>	diff(Iterable<T> before, Iterable<T> after, NaturalKey<T,K> naturalKey)	Creates a delta from two datasets, using a default item equivalence function.
static <T,K> Delta<T,K>	diff(Iterable<T> before, Iterable<T> after, NaturalKey<T,K> naturalKey, Equivalence<T> equivalence)	Creates a delta from two datasets.
static <T,U,K> Delta<T,K>	diff(Iterable<T> before, Iterable<T> after, NaturalKey<T,K> naturalKey, Essence<T,U> essence)	Creates a delta from two datasets, using an Essence function to distill items for comparison.
static <T,K> Delta<T,K>	diff(Map<K,T> before, Map<K,T> after)	Creates a delta from two datasets, using a default item equivalence function.
static <T,K> Delta<T,K>	diff(Map<K,T> before, Map<K,T> after, Equivalence<T> equivalence)	Creates a delta from two datasets.
static <T,U,K> Delta<T,K>	diff(Map<K,T> before, Map<K,T> after, Essence<T,U> essence)	Creates a delta from two datasets, using an Essence function to distill items for comparison.
static <T,K> Delta<T,K>	empty()	Returns an empty delta.
Optional<Operation<T>>	get(K key)	Retrieves an operation by the natural key of an item in the dataset.
Collection<T>	insertedItems()	Returns the inserted items of this delta.
Collection<Operation<T>>	inserts()	Returns the insert operations of this delta.
boolean	isEmpty()	Indicates whether this delta is empty.
Map<K,Operation<T>>	operations()	Returns the insert, update and delete operations of this delta.
Collection<T>	updatedItems()	Returns the updated items of this delta.
Collection<Operation<T>>	updates()	Returns the update operations of this delta.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

operations

public Map<K,Operation<T>> operations()

Returns the insert, update and delete operations of this delta.

Returns:

the operations of this delta

inserts

public Collection<Operation<T>> inserts()

Returns the insert operations of this delta.

Returns:

the insert operations of this delta

insertedItems

public Collection<T> insertedItems()

Returns the inserted items of this delta.

Returns:

the inserted items of this delta

updates

public Collection<Operation<T>> updates()

Returns the update operations of this delta.

Returns:

the update operations of this delta

updatedItems

public Collection<T> updatedItems()

Returns the updated items of this delta.

Returns:

the updated items of this delta

deletes

public Collection<Operation<T>> deletes()

Returns the delete operations of this delta.

Returns:

the delete operations of this delta

deletedItems

public Collection<T> deletedItems()

Returns the deleted items of this delta.

Returns:

the deleted items of this delta

get

public Optional<Operation<T>> get(K key)

Retrieves an operation by the natural key of an item in the dataset.

Parameters:

key - the natural key of an item affected by this delta

Returns:

a Optional containing the operation for the given key, or an empty Optional if no operation exists for the key

Throws:

NullPointerException - if key is null

isEmpty

public boolean isEmpty()

Indicates whether this delta is empty.

Returns:

true if this delta has no operations, false otherwise

apply

public Collection<T> apply(Iterable<T> items,
                           NaturalKey<T,K> naturalKey)

Applies this delta's inserts, updates and deletes to another dataset.

Parameters:

items - the dataset to which this delta will be applied

naturalKey - a function to derive natural keys for dataset items

Returns:

a new collection containing items with this delta applied

Throws:

DuplicateKeyException - if items contains any items with the same natural key, or if this delta contains an insert with the same key as an item in the dataset

NullPointerException - if items is null, any element in items is null, naturalKey is null or if naturalKey produces a null for any item

apply

public Map<K,T> apply(Map<K,T> items)

Applies this delta's inserts, updates and deletes to another dataset.

Parameters:

items - the dataset to which this delta will be applied

Returns:

a new collection containing items with this delta applied

Throws:

DuplicateKeyException - if this delta contains an insert with the same key as an item in the dataset

NullPointerException - if items is null, or if any key or value in items is null

combine

public Delta<T,K> combine(Delta<T,K> other)

Combines this delta with another delta, using a default item equivalence function. Applying a combined delta of A and B is equivalent to applying A, then B.

Parameters:

other - the other delta with which to combine

Returns:

a new combined delta

Throws:

InvalidCombination - if operations for the same natural key in the deltas cannot be combined

NullPointerException - if other is null

See Also:

Operation.combine(Operation)

combine

public <U> Delta<T,K> combine(Delta<T,K> other,
                                    Essence<T,U> essence)

Combines this delta with another delta, using an Essence function to distill items for comparison. Applying a combined delta of A and B is equivalent to applying A, then B.

Type Parameters:

U - the distilled type for equivalence comparisons

Parameters:

other - the other delta with which to combine

essence - a function to distill items down to their essential features for equivalence comparisons

Returns:

a new combined delta

Throws:

InvalidCombination - if operations for the same natural key in the deltas cannot be combined

NullPointerException - if other is null

See Also:

Operation.combine(Operation)

combine

public Delta<T,K> combine(Delta<T,K> other,
                                Equivalence<T> equivalence)

Combines this delta with another delta. Applying a combined delta of A and B is equivalent to applying A, then B.

Parameters:

other - the other delta with which to combine

equivalence - a function to determine whether two dataset items are equivalent

Returns:

a new combined delta

Throws:

InvalidCombination - if operations for the same natural key in the deltas cannot be combined

NullPointerException - if other is null or equivalence is null

See Also:

Operation.combine(Operation, Equivalence)

empty

public static <T,K> Delta<T,K> empty()

Returns an empty delta.

Type Parameters:

T - the type of items in the delta

K - the type of the items' natural keys

Returns:

an empty delta

diff

public static <T,K> Delta<T,K> diff(Iterable<T> before,
                                                Iterable<T> after,
                                                NaturalKey<T,K> naturalKey)

Creates a delta from two datasets, using a default item equivalence function.

Type Parameters:

T - the type of dataset items

K - the type of the items' natural keys

Parameters:

before - the dataset before changes were made

after - the dataset after changes were made

naturalKey - a function to derive natural keys for dataset items in the datasets

Returns:

a delta representing the difference between the two datasets in terms of inserts, updates and deletes

Throws:

DuplicateKeyException - if any items in before have the same natural key, or if any items in after have the same natural key

NullPointerException - if before is null, after is null, any element in before or after is null, naturalKey is null or if naturalKey produces a null for any item

diff

public static <T,U,K> Delta<T,K> diff(Iterable<T> before,
                                                        Iterable<T> after,
                                                        NaturalKey<T,K> naturalKey,
                                                        Essence<T,U> essence)

Creates a delta from two datasets, using an Essence function to distill items for comparison.

Type Parameters:

T - the type of dataset items

U - the distilled type for equivalence comparisons

K - the type of the items' natural keys

Parameters:

before - the dataset before changes were made

after - the dataset after changes were made

naturalKey - a function to derive natural keys for dataset items in the datasets

essence - a function to distill items down to their essential features for equivalence comparisons

Returns:

a delta representing the difference between the two datasets in terms of inserts, updates and deletes

Throws:

DuplicateKeyException - if any items in before have the same natural key, or if any items in after have the same natural key

NullPointerException - if before is null, after is null, any element in before or after is null, naturalKey is null or if naturalKey produces a null for any item

diff

public static <T,K> Delta<T,K> diff(Iterable<T> before,
                                                Iterable<T> after,
                                                NaturalKey<T,K> naturalKey,
                                                Equivalence<T> equivalence)

Creates a delta from two datasets.

Type Parameters:

T - the type of dataset items

K - the type of the items' natural keys

Parameters:

before - the dataset before changes were made

after - the dataset after changes were made

naturalKey - a function to derive natural keys for dataset items in the datasets

equivalence - a function to determine whether two dataset items are equivalent

Returns:

a delta representing the difference between the two datasets in terms of inserts, updates and deletes

Throws:

DuplicateKeyException - if any items in before have the same natural key, or if any items in after have the same natural key

NullPointerException - if before is null, after is null, any element in before or after is null, naturalKey is null, naturalKey produces a null for any item or if equivalence is null

diff

public static <T,K> Delta<T,K> diff(Map<K,T> before,
                                                Map<K,T> after)

Creates a delta from two datasets, using a default item equivalence function.

Type Parameters:

T - the type of dataset items

K - the type of the items' natural keys

Parameters:

before - the dataset before changes were made

after - the dataset after changes were made

Returns:

a delta representing the difference between the two datasets in terms of inserts, updates and deletes

Throws:

NullPointerException - if before is null, after is null, or if any key or value in before or after is null

diff

public static <T,U,K> Delta<T,K> diff(Map<K,T> before,
                                                        Map<K,T> after,
                                                        Essence<T,U> essence)

Creates a delta from two datasets, using an Essence function to distill items for comparison.

Type Parameters:

T - the type of dataset items

U - the distilled type for equivalence comparisons

K - the type of the items' natural keys

Parameters:

before - the dataset before changes were made

after - the dataset after changes were made

essence - a function to distill items down to their essential features for equivalence comparisons

Returns:

a delta representing the difference between the two datasets in terms of inserts, updates and deletes

Throws:

NullPointerException - if before is null, after is null, or if any key or value in before or after is null

diff

public static <T,K> Delta<T,K> diff(Map<K,T> before,
                                                Map<K,T> after,
                                                Equivalence<T> equivalence)

Creates a delta from two datasets.

Type Parameters:

T - the type of dataset items

K - the type of the items' natural keys

Parameters:

before - the dataset before changes were made

after - the dataset after changes were made

equivalence - a function to determine whether two dataset items are equivalent

Returns:

a delta representing the difference between the two datasets in terms of inserts, updates and deletes

Throws:

NullPointerException - if before is null, after is null, any key or value in before or after is null, or if equivalence is null