brown.tracingplane.baggageprotocol

Class BaggageReader

java.lang.Object

brown.tracingplane.baggageprotocol.BaggageReader

All Implemented Interfaces:

ElementReader

public class BaggageReader
extends java.lang.Object
implements ElementReader

Iterates over a list of atoms, interpreting them according to the baggage protocol; readers interpret data atoms and construct corresponding object representations.

Method Summary

Modifier and Type	Method and Description
static BaggageReader	create(java.lang.Iterable<java.nio.ByteBuffer> itbl)
static BaggageReader	create(java.util.Iterator<java.nio.ByteBuffer> it)
static BaggageReader	create(java.util.Iterator<java.nio.ByteBuffer> first, java.util.Iterator<java.nio.ByteBuffer> second, java.util.Iterator<java.nio.ByteBuffer> more)
boolean	didOverflow()
void	dropData() Drop remaining data atoms between here and the next child bag / end of bag.
void	dropDataAndChildren() Drop all remaining data atoms and child atoms in this bag, advancing to the next sibling / parent bag.
BagKey	enter() If there are no more children in the current bag, returns null.
boolean	enter(BagKey expect) Advances through the atoms until either the specified bag is encountered, or we encounter a bag that is lexicographically greater than the specified bag.
void	exit() Indicate the current child has finished parsing.
void	finish() Indicate that atom parsing has completed.
boolean	hasChild() Check to see whether the current atom is the header for a child bag.
boolean	hasData()
boolean	hasNext() Checks to see whether there are more atoms at the current level.
void	keepData() Add all remaining data atoms between here and the next child bag / end of bag to the list of unprocessed elements.
void	keepDataAndChildren() Add all remaining data atoms and children of this bag to the list of unprocessed elements.
java.nio.ByteBuffer	nextData()
java.util.List<java.nio.ByteBuffer>	overflowAtoms() If an overflow marker was encountered, we keep track of where the first occurrence of the overflow marker was encountered.
java.util.List<java.nio.ByteBuffer>	unprocessedAtoms() If some bags went unprocessed, their atoms are saved.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static BaggageReader create(java.lang.Iterable<java.nio.ByteBuffer> itbl)

create

public static BaggageReader create(java.util.Iterator<java.nio.ByteBuffer> it)

create

public static BaggageReader create(java.util.Iterator<java.nio.ByteBuffer> first,
                                   java.util.Iterator<java.nio.ByteBuffer> second,
                                   java.util.Iterator<java.nio.ByteBuffer> more)

hasNext

public boolean hasNext()

Checks to see whether there are more atoms at the current level. This is always true, unless the next atom is a prefix for a header at a level <= currentLevel, or we run out of atoms. When this method returns false, exit() should be called to return to the parent bag.

Returns:

true if there are more data elements or child bags to read; false if this bag is exhausted

hasData

public boolean hasData()

Specified by:

hasData in interface ElementReader

Returns:

true if the next atom is a data atom; false otherwise

hasChild

public boolean hasChild()

Check to see whether the current atom is the header for a child bag. This method can return false if the current atom is a data atom, or if the current atom is a header for a bag belonging to a parent

Returns:

true if the current atom is the header for a child bag; false otherwise

nextData

public java.nio.ByteBuffer nextData()

Specified by:

nextData in interface ElementReader

Returns:

the next atom if it is a data atom; null otherwise

dropData

public void dropData()

Drop remaining data atoms between here and the next child bag / end of bag. This means they will not be added to the list of unprocessed elements. The method keepData() lets you keep remaining data atoms as unprocessed elements instead if desired.

The default behavior for data atoms is as follows:

• If you do not attempt to read any data from a bag (eg, by jumping straight to a child bag), then all data is automatically added to the list of unprocessed elements.
• If you read some data from a bag, but not all of it, then the remaining data in the bag is discarded and not added as unprocessed

The methods dropData() and keepData() let the user control this behavior

Specified by:

dropData in interface ElementReader

dropDataAndChildren

public void dropDataAndChildren()

Drop all remaining data atoms and child atoms in this bag, advancing to the next sibling / parent bag. None of the atoms will be added to the list of unprocessed elements.

In general this method should not be used, as it is likely to violate the 'ignore and propagate' principle.

keepData

public void keepData()

Add all remaining data atoms between here and the next child bag / end of bag to the list of unprocessed elements. The method dropData() lets you instead drop the data items if desired.

The default behavior for data atoms is as follows:

• If you do not attempt to read any data from a bag (eg, by jumping straight to a child bag), then all data is automatically added to the list of unprocessed elements.
• If you read some data from a bag, but not all of it, then the remaining data in the bag is discarded and not added as unprocessed

The methods dropData() and keepData() let the user control this behavior

Specified by:

keepData in interface ElementReader

keepDataAndChildren

public void keepDataAndChildren()

Add all remaining data atoms and children of this bag to the list of unprocessed elements. The method (@link dropBag()} lets you instead drop the bag if desired.

The default behavior is to keep all child bags that are not processed, so a call to keepDataAndChildren() is not necessary

enter

public boolean enter(BagKey expect)

Advances through the atoms until either the specified bag is encountered, or we encounter a bag that is lexicographically greater than the specified bag. That is, if we encounter the bag, we enter the bag and advance to the next atom and return true. If this method returns false, we are at the first bag after where the expected bag would be

Parameters:

expect - the next BagKey to look for

Returns:

true if the BagKey is found and the bag was entered; false otherwise

enter

public BagKey enter()

If there are no more children in the current bag, returns null. Otherwise, advances to the next child, enters it, and returns its key.

Returns:

the key of the next child in this bag if there is one; null otherwise

exit

public void exit()

Indicate the current child has finished parsing. This method will drop any remaining data and/or child atoms that were not handled. After this call finishes, the next atom is expected to be a bag header of either a sibling, or a sibling of some parent, grandparent, or other ancester.

finish

public void finish()

Indicate that atom parsing has completed. Remaining data atoms will be discarded and remaining children will be treated as unprocessed

didOverflow

public boolean didOverflow()

Returns:

true if an overflow marker has been encountered parsing up to this point

overflowAtoms

public java.util.List<java.nio.ByteBuffer> overflowAtoms()

If an overflow marker was encountered, we keep track of where the first occurrence of the overflow marker was encountered. This consists of a path of atom headers followed by the overflow marker. These atoms can be re-merged with baggage atoms to re-add the overflow marker in the correct position. This method should only be called at the end of parsing. Upon calling this method, all remaining atoms will be traversed in an attempt to find trailing overflow markers. All remaining atoms are treated as unprocessed.

Returns:

a list of atoms if overflow was encountered, otherwise null

unprocessedAtoms

public java.util.List<java.nio.ByteBuffer> unprocessedAtoms()

If some bags went unprocessed, their atoms are saved. These atoms comprise the unprocessed data elements plus the appropriate headers. This method should only be called at the end of parsing. Upon calling this method, all remaining atoms will be traversed in an attempt to find trailing overflow markers. All remaining atoms are treated as unprocessed.

Returns:

a list of atoms if there were unprocessed atoms, otherwise null