Package org.apache.drill.exec.store.easy.json.parser

Interface ArrayListener

All Known Implementing Classes:

SimpleArrayListener, SimpleArrayListener.ListArrayListener, SimpleArrayListener.StructureArrayListener

public interface ArrayListener

Represents one level within array. The first time the parser sees the array element, it will call the #element(ValueDef) method with the look-ahead values visible to the parser. Since JSON is flexible, later data shapes may not necessarily follow the first shape. The implementation must handle this or throw an error if not supported.

When creating a multi-dimensional array, each array level is built one by one. each will receive the same type information (decreased by one array level.)

Then, while parsing, the parser calls events on the start and end of the array, as well as on each element.

The array listener is an attribute of a value listener, represent the "arrayness" of that value, if the value allows an array.

Elements

The array listener has a child listener that represents each element in the array. The structure parser asks this listener to create that child on the first element seen for the array. The structure parser provides "look-ahead" type information for that element, when available.

Three JSON-specific cases warrant attention:

1. The first occurrence of the array is empty: [ ]. In this case, the structure parser will defer asking for an element parser (and listener) until an actual value appears. The array listener is responsible for implementing some kind of "deferred type" logic to wait and see what kind of element appears later.
2. The first occurrence of the array has, as its first element, a null value. The structure parser will ask this listener to create an array child for the null value, but the listener has no type information. Since null values must be recorded (so we know how many appear in each array), the listener is forced to choose a type. Choose wisely as there is no way to know what type will appear in the future.
3. A generalized form of the above is that the structure parser only knows what it sees on the first element when it asks for an element child. In a well-formed file, that first token will predict the type of all future tokens. But, JSON allows anything. The first element might be null, an empty array, or a String. The second element could be anything else (a number or an object). The listener, as always is responsible for deciding how to handle type changes.

Multi-Dimensional Arrays

A multi-dimensional array is one of the form [ [ ... , that is, the parser returns multiple levels of array start tokens. In this case, listeners are structured as:

• ObjectListener for the enclosing object which has a
• FieldListener for the array value which has a
• ArrayListener for the array, which has a
• ValueListener for the elements. If the array is 1D, the nesting stops here. But if it is 2+D, then the value has a
• ArrayListener for the inner array, which has a
• ValueListener for the elements. And so on recursively for as many levels as needed or the array.

Method Summary

Modifier and Type	Method	Description
void	onElementEnd()	Called after each element of the array.
void	onElementStart()	Called for each element of the array.
void	onEnd()	Called at the end of a set of values for an array.
void	onStart()	Called at the entrance to each level (dimension) of an array.

Method Details

onStart

void onStart()

Called at the entrance to each level (dimension) of an array. That is, called when the structure parser accepts the [ token.

onElementStart

void onElementStart()

Called for each element of the array. The array element is represented by its own listener which receives the value of the element (if scalar) or element events (if structured.)

onElementEnd

void onElementEnd()

Called after each element of the array.

onEnd

void onEnd()

Called at the end of a set of values for an array. That is, called when the structure parser accepts the ] token.