Class TopNAggregator<K,V,T,E>

java.lang.Object

com.tangosol.util.aggregator.TopNAggregator<K,V,T,E>

Type Parameters:

K - the type of the Map entry keys

V - the type of the Map entry values

T - the type of the value to extract from

E - the type of the extracted value

All Implemented Interfaces:

ExternalizableLite, PortableObject, InvocableMap.EntryAggregator<K,V,E[]>, InvocableMap.StreamingAggregator<K, V, TopNAggregator.PartialResult<E>, E[]>, Serializable

public class TopNAggregator<K,V,T,E>
extends Object
implements InvocableMap.StreamingAggregator<K, V, TopNAggregator.PartialResult<E>, E[]>, ExternalizableLite, PortableObject

TopNAggregator is a ParallelAwareAggregator that aggregates the top N extracted values into an array. The extracted values must not be null, but do not need to be unique.

Since:

12.1.3

Author:

rhl 2013.04.24

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TopNAggregator.PartialResult<E>	The sorted partial result.

Nested classes/interfaces inherited from interface InvocableMap.StreamingAggregator

InvocableMap.StreamingAggregator.RetractionResult

Field Summary

Fields

Modifier and Type	Field	Description
protected Comparator<? super E>	m_comparator	The Comparator used to order the extracted values.
protected int	m_cResults	The maximum number of results to include in the aggregation result.
protected ValueExtractor<? super T, ? extends E>	m_extractor	The ValueExtractor used by this aggregator.
protected boolean	m_fParallel	True iff this aggregator is to be used in parallel.

Fields inherited from interface InvocableMap.StreamingAggregator

ALLOW_INCONSISTENCIES, BY_MEMBER, BY_PARTITION, CONTINUOUS, PARALLEL, PRESENT_ONLY, RETAINS_ENTRIES, SERIAL, STATE_CHECKPOINTABLE

Constructor Summary

Constructors

Constructor	Description
TopNAggregator()	Default constructor.
TopNAggregator(ValueExtractor<? super T, ? extends E> extractor, Comparator<? super E> comparator, int cResults)	Construct a TopNAggregator that will aggregate the top extracted values, as determined by the specified comparator.

Method Summary

Modifier and Type	Method	Description
boolean	accumulate(InvocableMap.Entry<? extends K, ? extends V> entry)	Accumulate one entry into the result.
int	characteristics()	A bit mask representing the set of characteristics of this aggregator.
boolean	combine(TopNAggregator.PartialResult<E> partialResult)	Merge another partial result into the result.
protected void	ensureInitialized()	Ensure that this aggregator is initialized.
boolean	equals(Object o)
E[]	finalizeResult()	Return the final result of the aggregation.
Comparator<? super E>	getComparator()	Obtain the comparator used by this aggregator.
TopNAggregator.PartialResult<E>	getPartialResult()	Return the partial result of the aggregation.
ValueExtractor<? super T, ? extends E>	getValueExtractor()	Obtain the extractor used by this aggregator.
int	hashCode()
void	readExternal(PofReader in)	Restore the contents of a user type instance by reading its state using the specified PofReader object.
void	readExternal(DataInput in)	Restore the contents of this object by loading the object's state from the passed DataInput object.
void	restoreState(Object oState)	Restore a maintenance-state snapshot into this empty supplied instance.
InvocableMap.StreamingAggregator.RetractionResult	retract(InvocableMap.Entry<? extends K, ? extends V> entry)	Retract the contribution of a single entry from the aggregation result.
Object	snapshotState()	Return a detached, serializer-compatible snapshot of the state required to continue incremental maintenance.
InvocableMap.StreamingAggregator<K, V, TopNAggregator.PartialResult<E>, E[]>	supply()	Create a new instance of this aggregator.
void	writeExternal(PofWriter out)	Save the contents of a POF user type instance by writing its state using the specified PofWriter object.
void	writeExternal(DataOutput out)	Save the contents of this object by storing the object's state into the passed DataOutput object.

Methods inherited from class Object

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

Methods inherited from interface InvocableMap.StreamingAggregator

accumulate, aggregate, finalizeResult, getMaintenanceStatus, isAllowInconsistencies, isByMember, isByPartition, isContinuous, isParallel, isPresentOnly, isRetainsEntries, isSerial, isStateCheckpointable, update

Field Details

m_fParallel

protected boolean m_fParallel

True iff this aggregator is to be used in parallel.

m_extractor

protected ValueExtractor<? super T, ? extends E> m_extractor

The ValueExtractor used by this aggregator.

m_comparator

protected Comparator<? super E> m_comparator

The Comparator used to order the extracted values.

m_cResults

protected int m_cResults

The maximum number of results to include in the aggregation result.

Constructor Details

TopNAggregator

public TopNAggregator()

Default constructor.

TopNAggregator

public TopNAggregator(ValueExtractor<? super T, ? extends E> extractor,
 Comparator<? super E> comparator,
 int cResults)

Construct a TopNAggregator that will aggregate the top extracted values, as determined by the specified comparator.

Parameters:

extractor - the extractor

comparator - the comparator for extracted values

cResults - the maximum number of results to return

Method Details

supply

public InvocableMap.StreamingAggregator<K, V, TopNAggregator.PartialResult<E>, E[]> supply()

Description copied from interface: InvocableMap.StreamingAggregator

Create a new instance of this aggregator.

Specified by:

supply in interface InvocableMap.StreamingAggregator<K,V,T,E>

Returns:

a StreamAggregator

accumulate

public boolean accumulate(InvocableMap.Entry<? extends K, ? extends V> entry)

Description copied from interface: InvocableMap.StreamingAggregator

Accumulate one entry into the result.

Specified by:

accumulate in interface InvocableMap.StreamingAggregator<K,V,T,E>

Parameters:

entry - the entry to accumulate into the aggregation result

Returns:

true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

retract

public InvocableMap.StreamingAggregator.RetractionResult retract(InvocableMap.Entry<? extends K, ? extends V> entry)

Description copied from interface: InvocableMap.StreamingAggregator

Retract the contribution of a single entry from the aggregation result.

When the supplied entry is a MapTrigger.Entry, an implementation should retract the entry's original value. Otherwise, it should retract the value represented by the supplied entry.

The default implementation cannot retract an entry and requires the caller to rebuild the aggregation result.

Specified by:

retract in interface InvocableMap.StreamingAggregator<K,V,T,E>

Parameters:

entry - the entry to retract

Returns:

the state of the aggregation result after the retraction

combine

public boolean combine(TopNAggregator.PartialResult<E> partialResult)

Description copied from interface: InvocableMap.StreamingAggregator

Merge another partial result into the result.

Specified by:

combine in interface InvocableMap.StreamingAggregator<K,V,T,E>

Parameters:

partialResult - the partial result to merge

Returns:

true to continue the aggregation, and false to signal to the caller that the result is ready and the aggregation can be short-circuited

getPartialResult

public TopNAggregator.PartialResult<E> getPartialResult()

Description copied from interface: InvocableMap.StreamingAggregator

Return the partial result of the aggregation.

Specified by:

getPartialResult in interface InvocableMap.StreamingAggregator<K,V,T,E>

Returns:

the partial result of the aggregation

finalizeResult

public E[] finalizeResult()

Description copied from interface: InvocableMap.StreamingAggregator

Return the final result of the aggregation.

Specified by:

finalizeResult in interface InvocableMap.StreamingAggregator<K,V,T,E>

Returns:

the final result of the aggregation

characteristics

public int characteristics()

Description copied from interface: InvocableMap.StreamingAggregator

A bit mask representing the set of characteristics of this aggregator.

By default, characteristics are a combination of InvocableMap.StreamingAggregator.PARALLEL and InvocableMap.StreamingAggregator.RETAINS_ENTRIES, which is sub-optimal and should be overridden by the aggregator implementation if the aggregator does not need to retain entries (which is often the case).

Specified by:

characteristics in interface InvocableMap.StreamingAggregator<K,V,T,E>

Returns:

a bit mask representing the set of characteristics of this aggregator

See Also:

• InvocableMap.StreamingAggregator.ALLOW_INCONSISTENCIES
• InvocableMap.StreamingAggregator.BY_MEMBER
• InvocableMap.StreamingAggregator.BY_PARTITION
• InvocableMap.StreamingAggregator.CONTINUOUS
• InvocableMap.StreamingAggregator.STATE_CHECKPOINTABLE
• InvocableMap.StreamingAggregator.PARALLEL
• InvocableMap.StreamingAggregator.PRESENT_ONLY
• InvocableMap.StreamingAggregator.RETAINS_ENTRIES
• InvocableMap.StreamingAggregator.SERIAL

snapshotState

public Object snapshotState()

Description copied from interface: InvocableMap.StreamingAggregator

Return a detached, serializer-compatible snapshot of the state required to continue incremental maintenance.

This method is used only when InvocableMap.StreamingAggregator.STATE_CHECKPOINTABLE is advertised. The default implementation does not support state checkpointing.

Specified by:

snapshotState in interface InvocableMap.StreamingAggregator<K,V,T,E>

Returns:

a detached maintenance-state snapshot

restoreState

public void restoreState(Object oState)

Description copied from interface: InvocableMap.StreamingAggregator

Restore a maintenance-state snapshot into this empty supplied instance.

This method is used only when InvocableMap.StreamingAggregator.STATE_CHECKPOINTABLE is advertised. The default implementation does not support state checkpointing.

Specified by:

restoreState in interface InvocableMap.StreamingAggregator<K,V,T,E>

Parameters:

oState - the snapshot returned by InvocableMap.StreamingAggregator.snapshotState()

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getValueExtractor

public ValueExtractor<? super T, ? extends E> getValueExtractor()

Obtain the extractor used by this aggregator.

Returns:

the extractor

getComparator

public Comparator<? super E> getComparator()

Obtain the comparator used by this aggregator.

Returns:

the comparator

ensureInitialized

protected void ensureInitialized()

Ensure that this aggregator is initialized.

readExternal

public void readExternal(DataInput in)
                  throws IOException

Description copied from interface: ExternalizableLite

Restore the contents of this object by loading the object's state from the passed DataInput object.

Specified by:

readExternal in interface ExternalizableLite

Parameters:

in - the DataInput stream to read data from in order to restore the state of this object

Throws:

IOException - if an I/O exception occurs

writeExternal

public void writeExternal(DataOutput out)
                   throws IOException

Description copied from interface: ExternalizableLite

Save the contents of this object by storing the object's state into the passed DataOutput object.

Specified by:

writeExternal in interface ExternalizableLite

Parameters:

out - the DataOutput stream to write the state of this object to

Throws:

IOException - if an I/O exception occurs

readExternal

public void readExternal(PofReader in)
                  throws IOException

Description copied from interface: PortableObject

Restore the contents of a user type instance by reading its state using the specified PofReader object.

Specified by:

readExternal in interface PortableObject

Parameters:

in - the PofReader from which to read the object's state

Throws:

IOException - if an I/O error occurs

writeExternal

public void writeExternal(PofWriter out)
                   throws IOException

Description copied from interface: PortableObject

Save the contents of a POF user type instance by writing its state using the specified PofWriter object.

Specified by:

writeExternal in interface PortableObject

Parameters:

out - the PofWriter to which to write the object's state

Throws:

IOException - if an I/O error occurs