ObjectReader (Genson 1.6 API)

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

All Methods Instance Methods Abstract 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()
```
    Throws:
    
    JsonStreamException
    
    NumberFormatException
    
    See Also:
    
    valueAsString()
  - valueAsLong
```
long valueAsLong()
```
    Throws:
    
    JsonStreamException
    
    NumberFormatException
    
    See Also:
    
    valueAsString()
  - valueAsDouble
```
double valueAsDouble()
```
    Throws:
    
    JsonStreamException
    
    NumberFormatException
    
    See Also:
    
    valueAsString()
  - valueAsShort
```
short valueAsShort()
```
    Throws:
    
    JsonStreamException
    
    NumberFormatException
    
    See Also:
    
    valueAsString()
  - valueAsFloat
```
float valueAsFloat()
```
    Throws:
    
    JsonStreamException
    
    NumberFormatException
    
    See Also:
    
    valueAsString()
  - valueAsBoolean
```
boolean valueAsBoolean()
```
    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()
```

Interface ObjectReader

Method Summary

Methods inherited from interface java.io.Closeable

Method Detail

beginObject

endObject

beginArray

endArray

nextObjectMetadata

next

hasNext

skipValue

getValueType

metadata

name

valueAsString

valueAsInt

valueAsLong

valueAsDouble

valueAsShort

valueAsFloat

valueAsBoolean

valueAsByteArray

enclosingType

column

row