Package org.apache.datasketches.quantiles

Class ItemsUnion<T>

java.lang.Object

org.apache.datasketches.quantiles.ItemsUnion<T>

Type Parameters:

T - type of item

public final class ItemsUnion<T>
extends Object

The API for Union operations for generic ItemsSketches

Author:

Lee Rhodes, Alexander Saydakov

Method Summary

Modifier and Type	Method	Description
int	getEffectiveK()	Returns the effective k of this Union.
static <T> ItemsUnion<T>	getInstance(Class<T> clazz, int maxK, Comparator<? super T> comparator)	Create an instance of ItemsUnion
static <T> ItemsUnion<T>	getInstance(Class<T> clazz, Comparator<? super T> comparator)	Create an instance of ItemsUnion with the default k
static <T> ItemsUnion<T>	getInstance(Class<T> clazz, org.apache.datasketches.memory.Memory srcMem, Comparator<? super T> comparator, ArrayOfItemsSerDe<T> serDe)	Heapify the given srcMem into a Union object.
static <T> ItemsUnion<T>	getInstance(ItemsSketch<T> sketch)	Create an instance of ItemsUnion based on ItemsSketch
int	getMaxK()	Returns the configured maxK of this Union.
ItemsSketch<T>	getResult()	Gets the result of this Union operation as a copy of the internal state.
ItemsSketch<T>	getResultAndReset()	Gets the result of this Union operation (without a copy) and resets this Union to the virgin state.
boolean	isDirect()	Returns true if this union is direct
boolean	isEmpty()	Returns true if this union is empty
void	reset()	Resets this Union to a virgin state.
byte[]	toByteArray(ArrayOfItemsSerDe<T> serDe)	Serialize this union to a byte array.
String	toString()	Returns summary information about the backing sketch.
String	toString(boolean sketchSummary, boolean dataDetail)	Returns summary information about the backing sketch.
void	union(org.apache.datasketches.memory.Memory srcMem, ArrayOfItemsSerDe<T> serDe)	Iterative union operation, which means this method can be repeatedly called.
void	union(ItemsSketch<T> sketchIn)	Iterative union operation, which means this method can be repeatedly called.
void	update(T dataItem)	Update this union with the given dataItem.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static <T> ItemsUnion<T> getInstance(Class<T> clazz,
                                            Comparator<? super T> comparator)

Create an instance of ItemsUnion with the default k

Type Parameters:

T - The sketch data type

Parameters:

clazz - The sketch class type

comparator - to compare items

Returns:

an instance of ItemsUnion

getInstance

public static <T> ItemsUnion<T> getInstance(Class<T> clazz,
                                            int maxK,
                                            Comparator<? super T> comparator)

Create an instance of ItemsUnion

Type Parameters:

T - The sketch data type

Parameters:

clazz - The sketch class type

maxK - determines the accuracy and size of the union and is a maximum. The effective k can be smaller due to unions with smaller k sketches. It is recommended that maxK be a power of 2 to enable unioning of sketches with a different k.

comparator - to compare items

Returns:

an instance of ItemsUnion

getInstance

public static <T> ItemsUnion<T> getInstance(Class<T> clazz,
                                            org.apache.datasketches.memory.Memory srcMem,
                                            Comparator<? super T> comparator,
                                            ArrayOfItemsSerDe<T> serDe)

Heapify the given srcMem into a Union object.

Type Parameters:

T - The sketch data type

Parameters:

clazz - The sketch class type A reference to srcMem will not be maintained internally.

srcMem - the given srcMem.

comparator - to compare items

serDe - an instance of ArrayOfItemsSerDe

Returns:

an instance of ItemsUnion

getInstance

public static <T> ItemsUnion<T> getInstance(ItemsSketch<T> sketch)

Create an instance of ItemsUnion based on ItemsSketch

Type Parameters:

T - The sketch data type

Parameters:

sketch - the basis of the union

Returns:

an instance of ItemsUnion

union

public void union(ItemsSketch<T> sketchIn)

Iterative union operation, which means this method can be repeatedly called. Merges the given sketch into this union object. The given sketch is not modified. It is required that the ratio of the two K's be a power of 2. This is easily satisfied if each of the K's are already a power of 2. If the given sketch is null or empty it is ignored.

It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

Parameters:

sketchIn - the sketch to be merged into this one.

union

public void union(org.apache.datasketches.memory.Memory srcMem,
                  ArrayOfItemsSerDe<T> serDe)

Iterative union operation, which means this method can be repeatedly called. Merges the given Memory image of a ItemsSketch into this union object. The given Memory object is not modified and a link to it is not retained. It is required that the ratio of the two K's be a power of 2. This is easily satisfied if each of the K's are already a power of 2. If the given sketch is null or empty it is ignored.

It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

Parameters:

srcMem - Memory image of sketch to be merged

serDe - an instance of ArrayOfItemsSerDe

update

public void update(T dataItem)

Update this union with the given dataItem.

Parameters:

dataItem - The given datum.

getResult

public ItemsSketch<T> getResult()

Gets the result of this Union operation as a copy of the internal state. This enables further union update operations on this state.

Returns:

the result of this Union operation

getResultAndReset

public ItemsSketch<T> getResultAndReset()

Gets the result of this Union operation (without a copy) and resets this Union to the virgin state.

Returns:

the result of this Union operation and reset.

reset

public void reset()

Resets this Union to a virgin state. Keeps maxK, comparator and clazz

isEmpty

public boolean isEmpty()

Returns true if this union is empty

Returns:

true if this union is empty

isDirect

public boolean isDirect()

Returns true if this union is direct

Returns:

true if this union is direct

getMaxK

public int getMaxK()

Returns the configured maxK of this Union.

Returns:

the configured maxK of this Union.

getEffectiveK

public int getEffectiveK()

Returns the effective k of this Union.

Returns:

the effective k of this Union.

toString

public String toString()

Returns summary information about the backing sketch.

Overrides:

toString in class Object

toString

public String toString(boolean sketchSummary,
                       boolean dataDetail)

Returns summary information about the backing sketch. Used for debugging.

Parameters:

sketchSummary - if true includes sketch summary

dataDetail - if true includes data detail

Returns:

summary information about the sketch.

toByteArray

public byte[] toByteArray(ArrayOfItemsSerDe<T> serDe)

Serialize this union to a byte array. Result is an ItemsSketch, serialized in an unordered, non-compact form. The resulting byte[] can be passed to getInstance for either a sketch or union.

Parameters:

serDe - an instance of ArrayOfItemsSerDe

Returns:

byte array of this union