com.owlike.genson.stream

Interface ObjectReader

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

JsonReader

public interface ObjectReader
extends Closeable

ObjectReader is part of the streaming api, it's implementations allow you to read data from the stream. The root of the input should always be a object, an array or a literal. There may be some differences between implementations if they try to be compliant with their format specification.

• To read an array call beginArray() then use hasNext() to check if there is a next element and then call next() to advance. When you call next in an array it will read the next value and return its type ValueType. Use it to check values type and to retrieve its value (if it is a literal) use one of valueAsXXX methods, otherwise it is an array or object. When hasNext returns false terminate the array by calling endArray().
• To read a object call beginObject() then use hasNext() to check if there is a next property and then call next() to read the name/value pair and name() to retrieve its name. If the value is a literal retrieve its value with valueAsXXX methods, otherwise it is an array or object. When you finished reading all properties call endObject().
• Objects can also contain metadata as their first properties. To read object metadata you have two options:
  1. Just begin your object with beginObject and then retrieve the metadata that you want with metadata(nameOfTheMetadataProperty).
  2. Use nextObjectMetadata() to read the next objects metadata without calling beginObject. This is useful when you want to handle some metadata in a converter and then delegate the rest to another converter (that will call beginObject or again nextObjectMetadata, so for him it will be transparent that you retrieved already some metadata and he will still be able to retrieve the same data).
• To read a literal use valueAsXXX methods. Actual implementation allows literals as root and is relatively tolerant to wrong types, for example if the stream contains the string "123" but you want to retrieve it as a int, JsonReader.valueAsInt() will parse it and return 123. It does also conversion between numeric types (double <-> int etc).
• To skip a value use skipValue(). If the value is an object or an array it will skip all its content.

Here is an example if you want to use directly the streaming api instead of the databind api (or if you write a custom converter or deserializer).

 public static void main(String[] args) {
        // we will read from json to Person
        Person.read(new JsonReader("{\"name\":\"eugen\",\"age\":26, \"childrenYearOfBirth\":[]}"));
 }
 
 class Person {
        String name;
        int age;
        List<Integer> childrenYearOfBirth;
 
        public static Person read(ObjectReader reader) {
                Person p = new Person();
                for (; reader.hasNext();) {
                        if ("name".equals(reader.name()))
                                p.name = reader.valueAsString();
                        else if ("age".equals(reader.name()))
                                p.age = reader.valueAsInt();
                        else if ("childrenYearOfBirth".equals(reader.name())) {
                                if (reader.getValueType() == TypeValue.NULL)
                                        p.childrenYearOfBirth = null;
                                else {
                                        reader.beginArray();
                                        p.childrenYearOfBirth = new ArrayList<Integer>();
                                        for (int i = 0; reader.hasNext(); i++)
                                                p.childrenYearOfBirth.add(reader.valueAsInt());
                                        reader.endArray();
                                }
                        }
                }
                return p;
        }
 }
 

Author:

eugen

See Also:

ValueType, JsonReader, ObjectWriter, JsonWriter

Method Summary

Methods

Modifier and Type	Method and Description
ObjectReader	beginArray() Starts reading an array.
ObjectReader	beginObject() Starts reading a object.
int	column()
JsonType	enclosingType()
ObjectReader	endArray() Ends the array.
ObjectReader	endObject() Ends the object.
ValueType	getValueType()
boolean	hasNext()
String	metadata(String name)
String	name()
ValueType	next() If we are in a object it will read the next name/value pair and if we are in an array it will read the next value (except if value is of complex type, in that case after the call to next() you must use one of beginXXX methods).
ObjectReader	nextObjectMetadata() Will read nexts object metadata.
int	row()
ObjectReader	skipValue() If the value is of complex type it will skip its content.
boolean	valueAsBoolean()
byte[]	valueAsByteArray()
double	valueAsDouble()
float	valueAsFloat()
int	valueAsInt()
long	valueAsLong()
short	valueAsShort()
String	valueAsString()

Methods inherited from interface java.io.Closeable

close

Method Detail

beginObject

ObjectReader beginObject()

Starts reading a object. Objects contain name/value pairs. Call endObject() when the objects contains no more properties.

Returns:

a reference to the reader.

Throws:

JsonStreamException

endObject

ObjectReader endObject()

Ends the object. If you were not in an object or the object contains more data, an exception will be thrown.

Returns:

a reference to the reader.

Throws:

JsonStreamException

beginArray

ObjectReader beginArray()

Starts reading an array. Arrays contain only values. Call endArray() when the array contains no more values.

Returns:

a reference to the reader.

Throws:

JsonStreamException

endArray

ObjectReader endArray()

Ends the array. If you were not in an array or the array contains more data, an exception will be thrown.

Returns:

a reference to the reader.

Throws:

JsonStreamException

nextObjectMetadata

ObjectReader nextObjectMetadata()

Will read nexts object metadata. You can call this method as many times as you want, with the condition that you use only metadata(String) method. For example if you call beginObject() you wont be able to do it anymore (however you still can retrieve the metadata!).

Returns:

a reference to the reader.

Throws:

JsonStreamException

next

ValueType next()

If we are in a object it will read the next name/value pair and if we are in an array it will read the next value (except if value is of complex type, in that case after the call to next() you must use one of beginXXX methods).

Returns:

the type of the value, see ValueType for possible types.

Throws:

JsonStreamException

hasNext

boolean hasNext()

Returns:

true if there is a next property or value, false otherwise.

Throws:

JsonStreamException

skipValue

ObjectReader skipValue()

If the value is of complex type it will skip its content.

Returns:

a reference to the reader.

Throws:

JsonStreamException

getValueType

ValueType getValueType()

Returns:

The type of current value.

See Also:

ValueType

metadata

String metadata(String name)

Parameters:

name - the name of the metadata to retrieve.

Returns:

value of metadata with name as key or null if there is no such metadata.

Throws:

JsonStreamException

name

String name()

Returns:

the name of current property, valid only if we are in a object and you called next() before.

Throws:

JsonStreamException

valueAsString

String valueAsString()

Returns:

the current value as a String. It will try to convert the actual value to String if its not of that type.

Throws:

JsonStreamException

valueAsInt

int valueAsInt()

Returns:

Throws:

JsonStreamException

NumberFormatException

See Also:

valueAsString()

valueAsLong

long valueAsLong()

Returns:

Throws:

JsonStreamException

NumberFormatException

See Also:

valueAsString()

valueAsDouble

double valueAsDouble()

Returns:

Throws:

JsonStreamException

NumberFormatException

See Also:

valueAsString()

valueAsShort

short valueAsShort()

Returns:

Throws:

JsonStreamException

NumberFormatException

See Also:

valueAsString()

valueAsFloat

float valueAsFloat()

Returns:

Throws:

JsonStreamException

NumberFormatException

See Also:

valueAsString()

valueAsBoolean

boolean valueAsBoolean()

Returns:

Throws:

JsonStreamException

See Also:

valueAsString()

valueAsByteArray

byte[] valueAsByteArray()

Returns:

the incoming base64 string converted to a byte array.

Throws:

JsonStreamException

enclosingType

JsonType enclosingType()

column

int column()

row

int row()