Package org.elasticsearch.common.xcontent

Class ObjectParser<Value,Context>

java.lang.Object

org.elasticsearch.common.xcontent.AbstractObjectParser<Value,Context>

org.elasticsearch.common.xcontent.ObjectParser<Value,Context>

All Implemented Interfaces:

BiFunction<XContentParser,Context,Value>, ContextParser<Context,Value>

public final class ObjectParser<Value,Context>
extends AbstractObjectParser<Value,Context>

A declarative, stateless parser that turns XContent into setter calls. A single parser should be defined for each object being parsed, nested elements can be added via AbstractObjectParser.declareObject(BiConsumer, ContextParser, ParseField) which should be satisfied where possible by passing another instance of ObjectParser, this one customized for that Object.

This class works well for object that do have a constructor argument or that can be built using information available from earlier in the XContent. For objects that have constructors with required arguments that are specified on the same level as other fields see ConstructingObjectParser.

Instances of ObjectParser should be setup by declaring a constant field for the parsers and declaring all fields in a static block just below the creation of the parser. Like this:

   private static final ObjectParser<Thing, SomeContext> PARSER = new ObjectParser<>("thing", Thing::new));
   static {
       PARSER.declareInt(Thing::setMineral, new ParseField("mineral"));
       PARSER.declareInt(Thing::setFruit, new ParseField("fruit"));
   }
 

It's highly recommended to use the high level declare methods like AbstractObjectParser.declareString(BiConsumer, ParseField) instead of declareField(org.elasticsearch.common.xcontent.ObjectParser.Parser<Value, Context>, org.elasticsearch.common.ParseField, org.elasticsearch.common.xcontent.ObjectParser.ValueType) which can be used to implement exceptional parsing operations not covered by the high level methods.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ObjectParser.NamedObjectParser<T,Context>	Functional interface for instantiating and parsing named objects.
static interface	ObjectParser.Parser<Value,Context>
static interface	ObjectParser.UnknownFieldConsumer<Value>	Defines how to consume a parsed undefined field
static class	ObjectParser.ValueType

Constructor Summary

Constructors

Constructor	Description
ObjectParser(String name)	Creates a new ObjectParser instance with a name.
ObjectParser(String name, boolean ignoreUnknownFields, Supplier<Value> valueSupplier)	Creates a new ObjectParser instance with a name.
ObjectParser(String name, Supplier<Value> valueSupplier)	Creates a new ObjectParser instance with a name.
ObjectParser(String name, ObjectParser.UnknownFieldConsumer<Value> unknownFieldConsumer, Supplier<Value> valueSupplier)	Creates a new ObjectParser instance with a name.

Method Summary

Modifier and Type	Method	Description
Value	apply(XContentParser parser, Context context)
<T> void	declareField(BiConsumer<Value,T> consumer, ContextParser<Context,T> parser, ParseField parseField, ObjectParser.ValueType type)	Declare some field.
void	declareField(ObjectParser.Parser<Value,Context> p, ParseField parseField, ObjectParser.ValueType type)
<T> void	declareNamedObjects(BiConsumer<Value,List<T>> consumer, ObjectParser.NamedObjectParser<T,Context> namedObjectParser, Consumer<Value> orderedModeCallback, ParseField field)	Declares named objects in the style of highlighting's field element.
<T> void	declareNamedObjects(BiConsumer<Value,List<T>> consumer, ObjectParser.NamedObjectParser<T,Context> namedObjectParser, ParseField field)	Declares named objects in the style of aggregations.
<T> void	declareObjectOrDefault(BiConsumer<Value,T> consumer, BiFunction<XContentParser,Context,T> objectParser, Supplier<T> defaultValue, ParseField field)
static <Value,ElementValue> BiConsumer<Value,List<ElementValue>>	fromList(Class<ElementValue> c, BiConsumer<Value,ElementValue[]> consumer)	Adapts an array (or varags) setter into a list setter.
String	getName()	Get the name of the parser.
Value	parse(XContentParser parser, Context context)	Parses a Value from the given XContentParser
Value	parse(XContentParser parser, Value value, Context context)	Parses a Value from the given XContentParser
String	toString()

Methods inherited from class org.elasticsearch.common.xcontent.AbstractObjectParser

declareBoolean, declareDouble, declareDoubleArray, declareField, declareFieldArray, declareFloat, declareFloatArray, declareInt, declareIntArray, declareLong, declareLongArray, declareObject, declareObjectArray, declareString, declareStringArray, declareStringOrNull

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.function.BiFunction

andThen

Constructor Detail

ObjectParser

public ObjectParser(String name)

Creates a new ObjectParser instance with a name. This name is used to reference the parser in exceptions and messages.

ObjectParser

public ObjectParser(String name,
                    @Nullable
                    Supplier<Value> valueSupplier)

Creates a new ObjectParser instance with a name.

Parameters:

name - the parsers name, used to reference the parser in exceptions and messages.

valueSupplier - a supplier that creates a new Value instance used when the parser is used as an inner object parser.

ObjectParser

public ObjectParser(String name,
                    boolean ignoreUnknownFields,
                    @Nullable
                    Supplier<Value> valueSupplier)

Creates a new ObjectParser instance with a name.

Parameters:

name - the parsers name, used to reference the parser in exceptions and messages.

ignoreUnknownFields - Should this parser ignore unknown fields? This should generally be set to true only when parsing responses from external systems, never when parsing requests from users.

valueSupplier - a supplier that creates a new Value instance used when the parser is used as an inner object parser.

ObjectParser

public ObjectParser(String name,
                    ObjectParser.UnknownFieldConsumer<Value> unknownFieldConsumer,
                    @Nullable
                    Supplier<Value> valueSupplier)

Creates a new ObjectParser instance with a name.

Parameters:

name - the parsers name, used to reference the parser in exceptions and messages.

unknownFieldConsumer - how to consume parsed unknown fields

valueSupplier - a supplier that creates a new Value instance used when the parser is used as an inner object parser.

Method Detail

fromList

public static <Value,ElementValue> BiConsumer<Value,List<ElementValue>> fromList(Class<ElementValue> c,
                                                                                             BiConsumer<Value,ElementValue[]> consumer)

Adapts an array (or varags) setter into a list setter.

parse

public Value parse(XContentParser parser,
                   Context context)
            throws IOException

Parses a Value from the given XContentParser

Parameters:

parser - the parser to build a value from

context - context needed for parsing

Returns:

a new value instance drawn from the provided value supplier on ObjectParser(String, Supplier)

Throws:

IOException - if an IOException occurs.

parse

public Value parse(XContentParser parser,
                   Value value,
                   Context context)
            throws IOException

Parses a Value from the given XContentParser

Parameters:

parser - the parser to build a value from

value - the value to fill from the parser

context - a context that is passed along to all declared field parsers

Returns:

the parsed value

Throws:

IOException - if an IOException occurs.

apply

public Value apply(XContentParser parser,
                   Context context)

declareField

public void declareField(ObjectParser.Parser<Value,Context> p,
                         ParseField parseField,
                         ObjectParser.ValueType type)

declareField

public <T> void declareField(BiConsumer<Value,T> consumer,
                             ContextParser<Context,T> parser,
                             ParseField parseField,
                             ObjectParser.ValueType type)

Description copied from class: AbstractObjectParser

Declare some field. Usually it is easier to use AbstractObjectParser.declareString(BiConsumer, ParseField) or AbstractObjectParser.declareObject(BiConsumer, ContextParser, ParseField) rather than call this directly.

Specified by:

declareField in class AbstractObjectParser<Value,Context>

declareObjectOrDefault

public <T> void declareObjectOrDefault(BiConsumer<Value,T> consumer,
                                       BiFunction<XContentParser,Context,T> objectParser,
                                       Supplier<T> defaultValue,
                                       ParseField field)

declareNamedObjects

public <T> void declareNamedObjects(BiConsumer<Value,List<T>> consumer,
                                    ObjectParser.NamedObjectParser<T,Context> namedObjectParser,
                                    Consumer<Value> orderedModeCallback,
                                    ParseField field)

Description copied from class: AbstractObjectParser

Declares named objects in the style of highlighting's field element. These are usually named inside and object like this:

 
 {
   "highlight": {
     "fields": {        <------ this one
       "title": {},
       "body": {},
       "category": {}
     }
   }
 }
 
 

but, when order is important, some may be written this way:

 
 {
   "highlight": {
     "fields": [        <------ this one
       {"title": {}},
       {"body": {}},
       {"category": {}}
     ]
   }
 }
 
 

This is because json doesn't enforce ordering. Elasticsearch reads it in the order sent but tools that generate json are free to put object members in an unordered Map, jumbling them. Thus, if you care about order you can send the object in the second way. See NamedObjectHolder in ObjectParserTests for examples of how to invoke this.

Specified by:

declareNamedObjects in class AbstractObjectParser<Value,Context>

Parameters:

consumer - sets the values once they have been parsed

namedObjectParser - parses each named object

orderedModeCallback - called when the named object is parsed using the "ordered" mode (the array of objects)

field - the field to parse

declareNamedObjects

public <T> void declareNamedObjects(BiConsumer<Value,List<T>> consumer,
                                    ObjectParser.NamedObjectParser<T,Context> namedObjectParser,
                                    ParseField field)

Description copied from class: AbstractObjectParser

Declares named objects in the style of aggregations. These are named inside and object like this:

 
 {
   "aggregations": {
     "name_1": { "aggregation_type": {} },
     "name_2": { "aggregation_type": {} },
     "name_3": { "aggregation_type": {} }
     }
   }
 }
 
 

Unlike the other version of this method, "ordered" mode (arrays of objects) is not supported. See NamedObjectHolder in ObjectParserTests for examples of how to invoke this.

Specified by:

declareNamedObjects in class AbstractObjectParser<Value,Context>

Parameters:

consumer - sets the values once they have been parsed

namedObjectParser - parses each named object

field - the field to parse

getName

public String getName()

Get the name of the parser.

Specified by:

getName in class AbstractObjectParser<Value,Context>

toString

public String toString()

Overrides:

toString in class Object