com.amazon.carbonado.cursor
Class GroupedCursor<S,G>

java.lang.Object
  com.amazon.carbonado.cursor.AbstractCursor<G>
      com.amazon.carbonado.cursor.GroupedCursor<S,G>

Type Parameters:

S - source type, can be anything

G - aggregate type, can be anything

All Implemented Interfaces:

Cursor<G>

public abstract class GroupedCursor<S,G>
extends AbstractCursor<G>

Abstract cursor for aggregation and finding distinct data. The source cursor must be ordered in some fashion by the grouping properties. The arrangement of properties must match, but it does not matter if they are ascending or descending.

Author:

Brian S O'Neill

See Also:

SortedCursor

Constructor Summary

protected	GroupedCursor(Cursor<S> cursor, Class<S> type, String... groupProperties) Create a GroupedCursor using properties to define the group comparator.
protected	GroupedCursor(Cursor<S> cursor, Comparator<S> groupComparator) Create a GroupedCursor with an existing group comparator.

Method Summary

protected abstract void	addToGroup(S groupMember) This method is called when more entries are found for the current group.
protected abstract void	beginGroup(S groupLeader) This method is called for the first entry in a group.
void	close() Call close to release any resources being held by this cursor.
Comparator<S>	comparator() Returns the comparator used to identify group boundaries.
protected abstract G	finishGroup() This method is called when a group is finished, and it can return an aggregate.
boolean	hasNext() Returns true if this cursor has more elements.
G	next() Returns the next element from this cursor.
int	skipNext(int amount) Skips forward by the specified amount of elements, returning the actual amount skipped.

Methods inherited from class com.amazon.carbonado.cursor.AbstractCursor

copyInto, copyInto, toList, toList

Methods inherited from class java.lang.Object

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

Constructor Detail

GroupedCursor

protected GroupedCursor(Cursor<S> cursor,
                        Comparator<S> groupComparator)

Create a GroupedCursor with an existing group comparator. The comparator defines the ordering of the source cursor, and it should be a partial odering. If group comparator defines a total ordering, then all groups have one member.

Parameters:

cursor - source of elements which must be ordered properly

groupComparator - comparator which defines ordering of source cursor

GroupedCursor

protected GroupedCursor(Cursor<S> cursor,
                        Class<S> type,
                        String... groupProperties)

Create a GroupedCursor using properties to define the group comparator. The set of properties defines the ordering of the source cursor, and it should be a partial ordering. If properties define a total ordering, then all groups have one member.

Parameters:

cursor - source of elements which must be ordered properly

type - type of storable to create cursor for

groupProperties - list of properties to group by

Throws:

IllegalArgumentException - if any property is null or not a member of storable type

Method Detail

comparator

public Comparator<S> comparator()

Returns the comparator used to identify group boundaries.

beginGroup

protected abstract void beginGroup(S groupLeader)
                            throws FetchException

This method is called for the first entry in a group. This method is not called again until after finishGroup is called.

Parameters:

groupLeader - first entry in group

Throws:

FetchException

addToGroup

protected abstract void addToGroup(S groupMember)
                            throws FetchException

This method is called when more entries are found for the current group. This method is not called until after beginGroup has been called. It may called multiple times until finishGroup is called.

Parameters:

groupMember - additional entry in group

Throws:

FetchException

finishGroup

protected abstract G finishGroup()
                          throws FetchException

This method is called when a group is finished, and it can return an aggregate. Simply return null if aggregate should be filtered out.

Returns:

aggregate, or null to filter it out

Throws:

FetchException

close

public void close()
           throws FetchException

Description copied from interface: Cursor

Call close to release any resources being held by this cursor. Further operations on this cursor will behave as if there are no results.

Throws:

FetchException

hasNext

public boolean hasNext()
                throws FetchException

Description copied from interface: Cursor

Returns true if this cursor has more elements. In other words, returns true if next would return an element rather than throwing an exception.

Throws:

FetchException - if storage layer throws an exception

next

public G next()
       throws FetchException

Description copied from interface: Cursor

Returns the next element from this cursor. This method may be called repeatedly to iterate through the results.

Throws:

FetchException - if storage layer throws an exception

skipNext

public int skipNext(int amount)
             throws FetchException

Description copied from interface: Cursor

Skips forward by the specified amount of elements, returning the actual amount skipped. The actual amount is less than the requested amount only if the end of the results was reached.

Specified by:

skipNext in interface Cursor<G>

Overrides:

skipNext in class AbstractCursor<G>

Parameters:

amount - maximum amount of elements to skip

Returns:

actual amount skipped

Throws:

FetchException - if storage layer throws an exception