org.apache.hadoop.hdfs.util
Class Diff<K,E extends Diff.Element<K>>

java.lang.Object
  org.apache.hadoop.hdfs.util.Diff<K,E>

Type Parameters:

K - The key type.

E - The element type, which must implement Diff.Element interface.

public class Diff<K,E extends Diff.Element<K>>
extends Object

The difference between the current state and a previous state of a list. Given a previous state of a set and a sequence of create, delete and modify operations such that the current state of the set can be obtained by applying the operations on the previous state, the following algorithm construct the difference between the current state and the previous state of the set.

 Two lists are maintained in the algorithm:
 - c-list for newly created elements
 - d-list for the deleted elements

 Denote the state of an element by the following
   (0, 0): neither in c-list nor d-list
   (c, 0): in c-list but not in d-list
   (0, d): in d-list but not in c-list
   (c, d): in both c-list and d-list

 For each case below, ( , ) at the end shows the result state of the element.

 Case 1. Suppose the element i is NOT in the previous state.           (0, 0)
   1.1. create i in current: add it to c-list                          (c, 0)
   1.1.1. create i in current and then create: impossible
   1.1.2. create i in current and then delete: remove it from c-list   (0, 0)
   1.1.3. create i in current and then modify: replace it in c-list    (c', 0)

   1.2. delete i from current: impossible

   1.3. modify i in current: impossible

 Case 2. Suppose the element i is ALREADY in the previous state.       (0, 0)
   2.1. create i in current: impossible

   2.2. delete i from current: add it to d-list                        (0, d)
   2.2.1. delete i from current and then create: add it to c-list      (c, d)
   2.2.2. delete i from current and then delete: impossible
   2.2.2. delete i from current and then modify: impossible

   2.3. modify i in current: put it in both c-list and d-list          (c, d)
   2.3.1. modify i in current and then create: impossible
   2.3.2. modify i in current and then delete: remove it from c-list   (0, d)
   2.3.3. modify i in current and then modify: replace it in c-list    (c', d)
 

Nested Class Summary

static class	Diff.Container<E> Containing exactly one element.
static interface	Diff.Element<K> An interface for the elements in a Diff.
static class	Diff.ListType
static interface	Diff.Processor<E> An interface for passing a method in order to process elements.
static class	Diff.UndoInfo<E> Undo information for some operations such as delete(E) and modify(Element, Element).

Constructor Summary

protected	Diff()
protected	Diff(List<E> created, List<E> deleted)

Method Summary

Diff.Container<E>	accessCurrent(K name) Find an element in the current state.
Diff.Container<E>	accessPrevious(K name) Find an element in the previous state.
List<E>	apply2Current(List<E> current) Apply the reverse of this diff to current state in order to obtain the previous state.
List<E>	apply2Previous(List<E> previous) Apply this diff to previous state in order to obtain current state.
void	combinePosterior(Diff<K,E> posterior, Diff.Processor<E> deletedProcesser) Combine this diff with a posterior diff.
int	create(E element) Create an element in current state.
Diff.UndoInfo<E>	delete(E element) Delete an element from current state.
List<E>	getList(Diff.ListType type)
boolean	isEmpty()
Diff.UndoInfo<E>	modify(E oldElement, E newElement) Modify an element in current state.
E	search(Diff.ListType type, K name)
protected static <K,E extends Comparable<K>> int	search(List<E> elements, K name) Search the element from the list.
int	searchIndex(Diff.ListType type, K name)
String	toString()
void	undoCreate(E element, int insertionPoint) Undo the previous create(E) operation.
void	undoDelete(E element, Diff.UndoInfo<E> undoInfo) Undo the previous delete(E) operation.
void	undoModify(E oldElement, E newElement, Diff.UndoInfo<E> undoInfo) Undo the previous modify(E, E) operation.

Methods inherited from class java.lang.Object

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

Constructor Detail

Diff

protected Diff()

Diff

protected Diff(List<E> created,
               List<E> deleted)

Method Detail

search

protected static <K,E extends Comparable<K>> int search(List<E> elements,
                                                        K name)

Search the element from the list.

Returns:

-1 if the list is null; otherwise, return the insertion point defined in Collections.binarySearch(List, Object). Note that, when the list is null, -1 is the correct insertion point.

getList

public List<E> getList(Diff.ListType type)

Returns:

the created list, which is never null.

searchIndex

public int searchIndex(Diff.ListType type,
                       K name)

search

public E search(Diff.ListType type,
                K name)

Returns:

null if the element is not found; otherwise, return the element in the created/deleted list.

isEmpty

public boolean isEmpty()

Returns:

true if no changes contained in the diff

create

public int create(E element)

Create an element in current state.

Returns:

the c-list insertion point for undo.

undoCreate

public void undoCreate(E element,
                       int insertionPoint)

Undo the previous create(E) operation. Note that the behavior is undefined if the previous operation is not create(E).

delete

public Diff.UndoInfo<E> delete(E element)

Delete an element from current state.

Returns:

the undo information.

undoDelete

public void undoDelete(E element,
                       Diff.UndoInfo<E> undoInfo)

Undo the previous delete(E) operation. Note that the behavior is undefined if the previous operation is not delete(E).

modify

public Diff.UndoInfo<E> modify(E oldElement,
                               E newElement)

Modify an element in current state.

Returns:

the undo information.

undoModify

public void undoModify(E oldElement,
                       E newElement,
                       Diff.UndoInfo<E> undoInfo)

Undo the previous modify(E, E) operation. Note that the behavior is undefined if the previous operation is not modify(E, E).

accessPrevious

public Diff.Container<E> accessPrevious(K name)

Find an element in the previous state.

Returns:

null if the element cannot be determined in the previous state since no change is recorded and it should be determined in the current state; otherwise, return a Diff.Container containing the element in the previous state. Note that the element can possibly be null which means that the element is not found in the previous state.

accessCurrent

public Diff.Container<E> accessCurrent(K name)

Find an element in the current state.

Returns:

null if the element cannot be determined in the current state since no change is recorded and it should be determined in the previous state; otherwise, return a Diff.Container containing the element in the current state. Note that the element can possibly be null which means that the element is not found in the current state.

apply2Previous

public List<E> apply2Previous(List<E> previous)

Apply this diff to previous state in order to obtain current state.

Returns:

the current state of the list.

apply2Current

public List<E> apply2Current(List<E> current)

Apply the reverse of this diff to current state in order to obtain the previous state.

Returns:

the previous state of the list.

combinePosterior

public void combinePosterior(Diff<K,E> posterior,
                             Diff.Processor<E> deletedProcesser)

Combine this diff with a posterior diff. We have the following cases:

 1. For (c, 0) in the posterior diff, check the element in this diff:
 1.1 (c', 0)  in this diff: impossible
 1.2 (0, d')  in this diff: put in c-list --> (c, d')
 1.3 (c', d') in this diff: impossible
 1.4 (0, 0)   in this diff: put in c-list --> (c, 0)
 This is the same logic as create(E).
 
 2. For (0, d) in the posterior diff,
 2.1 (c', 0)  in this diff: remove from c-list --> (0, 0)
 2.2 (0, d')  in this diff: impossible
 2.3 (c', d') in this diff: remove from c-list --> (0, d')
 2.4 (0, 0)   in this diff: put in d-list --> (0, d)
 This is the same logic as delete(E).
 
 3. For (c, d) in the posterior diff,
 3.1 (c', 0)  in this diff: replace the element in c-list --> (c, 0)
 3.2 (0, d')  in this diff: impossible
 3.3 (c', d') in this diff: replace the element in c-list --> (c, d')
 3.4 (0, 0)   in this diff: put in c-list and d-list --> (c, d)
 This is the same logic as modify(E, E).
 

Parameters:

posterior - The posterior diff to combine with.

deletedProcesser - process the deleted/overwritten elements in case 2.1, 2.3, 3.1 and 3.3.

toString

public String toString()

Overrides:

toString in class Object