Package org.apache.sling.discovery.commons

# Class InstancesDiff

java.lang.Object
org.apache.sling.discovery.commons.InstancesDiff

public final class InstancesDiff extends Object
The `InstancesDiff` allows to combine and filter two collections of `InstanceDescription` instances, an "old" collection and a "new" collection.

The comparison between `InstanceDescription` instances is done only on the basis of the Sling identifier. Two instances with the same Sling identifier are considered as equal.

Note: Each collection must contain only unique instances (no two instances with the same Sling identifier). Using the `InstancesDiff` with collections containing duplicated Sling id will throw an `IllegalArgumentException`.

Since:
  1.0.0

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`final class`
`InstancesDiff.InstanceCollection`
The `InstanceCollection` collection allows to filter the instances using a set of custom filter either implementing `InstanceFilter` or pre-defined ones.

## Constructor Summary

Constructors
Constructor
Description
`InstancesDiff(@NotNull Collection<T> oldInstances, @NotNull Collection<T> newInstances)`
Create a new `InstancesDiff` based on the provided old and new `Collection` collections of instances.
`InstancesDiff(@NotNull org.apache.sling.discovery.ClusterView oldView, @NotNull org.apache.sling.discovery.ClusterView newView)`
Create a new `InstancesDiff` based on the instances from the old and new `ClusterView` cluster views provided.
`InstancesDiff(@NotNull org.apache.sling.discovery.TopologyEvent event)`
Create a new `InstancesDiff` based on the instances from the old and new `TopologyView` topology views contained in the `TopologyEvent` event provided.
`InstancesDiff(@NotNull org.apache.sling.discovery.TopologyView oldView, @NotNull org.apache.sling.discovery.TopologyView newView)`
Create a new `InstancesDiff` based on the instances from the old and new `TopologyView` topology views provided.

## Method Summary

Modifier and Type
Method
Description
`@NotNull InstancesDiff.InstanceCollection`
`added()`
Returns the `InstanceCollection` collection containing the `InstanceDescription` instances that are contained in the new collection but not in the old collection.
`@NotNull InstancesDiff.InstanceCollection`
`all(boolean retainFromNewCollection)`
Returns the `InstanceSet` set containing the `InstanceDescription` instances that are contained in either the old or the new collection.
`@NotNull InstancesDiff.InstanceCollection`
`removed()`
Returns the `InstanceCollection` collection containing the `InstanceDescription` instances that are contained in the old collection but not in the new collection.
`@NotNull InstancesDiff.InstanceCollection`
`retained(boolean retainFromNewCollection)`
Returns the `InstanceSet` collection containing the `InstanceDescription` instances that are contained in both the old collection and the new collection.
`@NotNull InstancesDiff.InstanceCollection`
`retained(boolean retainFromNewCollection, boolean propertyChanged)`
Returns the `InstanceCollection` collection containing the `InstanceDescription` instances that are contained in both the old and the new collections.

### Methods inherited from class java.lang.Object

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

## Constructor Details

### InstancesDiff

public InstancesDiff(@NotNull @NotNull org.apache.sling.discovery.TopologyEvent event)
Create a new `InstancesDiff` based on the instances from the old and new `TopologyView` topology views contained in the `TopologyEvent` event provided.

Parameters:
  `event` - the non `null` event from which the old and new topology views are used for computing. If either of the topology views are `null`, then they will be substituted by an empty collection of instances.
Throws:
  `IllegalArgumentException` - if either of the collections contains duplicated Sling identifiers.

### InstancesDiff

public InstancesDiff(@NotNull @NotNull org.apache.sling.discovery.TopologyView oldView, @NotNull @NotNull org.apache.sling.discovery.TopologyView newView)
Create a new `InstancesDiff` based on the instances from the old and new `TopologyView` topology views provided.

Parameters:
  `oldView` - the non `null` old topology view from which the old collection is used for computing.
  `newView` - the non `null` new topology view form which the new collection is used for computing.
Throws:
  `IllegalArgumentException` - if either of the collections contains duplicated Sling identifiers.

### InstancesDiff

public InstancesDiff(@NotNull @NotNull org.apache.sling.discovery.ClusterView oldView, @NotNull @NotNull org.apache.sling.discovery.ClusterView newView)
Create a new `InstancesDiff` based on the instances from the old and new `ClusterView` cluster views provided.

Parameters:
  `oldView` - the non `null` old cluster view used for computing.
  `newView` - the non `null` new cluster view used for computing.
Throws:
  `IllegalArgumentException` - if either of the collections contains duplicated Sling identifiers.

### InstancesDiff

public InstancesDiff(@NotNull @NotNull Collection<T> oldInstances, @NotNull @NotNull Collection<T> newInstances)
Create a new `InstancesDiff` based on the provided old and new `Collection` collections of instances.

Type Parameters:
  `T` - the type of instance which must extend `InstanceDescription`.
Parameters:
  `oldInstances` - the non `null` old collection of instances used for computing.
  `newInstances` - the non `null` new collection of instances used for computing.
Throws:
  `IllegalArgumentException` - if either of the collections contains duplicated Sling identifiers.

## Method Details

### all

@NotNull public @NotNull InstancesDiff.InstanceCollection all(boolean retainFromNewCollection)
Returns the `InstanceSet` set containing the `InstanceDescription` instances that are contained in either the old or the new collection.

For `InstanceDescription` instances contained in both the old and the new collections, the method will retain those from either of the collections depending on the parameter #retainFromNewView.

Parameters:
  `retainFromNewCollection` - `true` in order to retain the instances from the new collection ; `false` in order to retain the instances from the old collection.
Returns:
  the `InstanceCollection` collection containing the `InstanceDescription` instances from both collections.

### added

@NotNull public @NotNull InstancesDiff.InstanceCollection added()
Returns the `InstanceCollection` collection containing the `InstanceDescription` instances that are contained in the new collection but not in the old collection.

Returns:
  the `InstanceCollection` collection containing the instances in the new topology collection but not in the old collection.

### removed

@NotNull public @NotNull InstancesDiff.InstanceCollection removed()
Returns the `InstanceCollection` collection containing the `InstanceDescription` instances that are contained in the old collection but not in the new collection.

Returns:
  the `InstanceSet` set containing the instances in the old collection but not in the new collection.

### retained

@NotNull public @NotNull InstancesDiff.InstanceCollection retained(boolean retainFromNewCollection)
Returns the `InstanceSet` collection containing the `InstanceDescription` instances that are contained in both the old collection and the new collection.

The method will retain the `InstanceDescription` instances from either of the collections depending on the parameter #retainFromNewView.

Parameters:
  `retainFromNewCollection` - `true` in order to retain the instances from the new collection ; `false` in order to retain the instances from the old collection.
Returns:
  the `InstanceCollection` collection containing the `InstanceDescription` instances contained in both collections.

### retained

@NotNull public @NotNull InstancesDiff.InstanceCollection retained(boolean retainFromNewCollection, boolean propertyChanged)
Returns the `InstanceCollection` collection containing the `InstanceDescription` instances that are contained in both the old and the new collections.

The method will retain the `InstanceDescription` instances from either of the collections depending on the parameter #retainFromNewView.

Parameters:
  `retainFromNewCollection` - `true` in order to retain the instances from the new collection ; `false` in order to retain the instances from the old collection.
  `propertyChanged` - `true` in order to keep only the instances which properties have changed between the old and new collections ; `false` in order to keep only the instances which properties have not changed.
Returns:
  the `InstanceCollection` collection containing the `InstanceDescription` instances contained in both views.