public final class ConstructingObjectParser<Value,Context extends ParseFieldMatcherSupplier> extends AbstractObjectParser<Value,Context>
ObjectParser but works with objects that have constructors whose arguments are mixed in with its other settings. Queries are
like this, for example ids requires types but always parses the values field on the same level. If
this doesn't sounds like what you want to parse have a look at
ObjectParser.declareNamedObjects(BiConsumer, ObjectParser.NamedObjectParser, Consumer, ParseField) which solves a slightly
different but similar sounding problem.
Anyway, ConstructingObjectParser parses the fields in the order that they are in the XContent, collecting constructor arguments and parsing and queueing normal fields until all constructor arguments are parsed. Then it builds the target object and replays the queued fields. Any fields that come in after the last constructor arguments are parsed and immediately applied to the target object just like ObjectParser.
Declaring a ConstructingObjectParser is intentionally quite similar to declaring an ObjectParser. The only
differences being that constructor arguments are declared with the consumer returned by the static constructorArg() method and
that ConstructingObjectParser's constructor takes a lambda that must build the target object from a list of constructor
arguments:
private static final ConstructingObjectParser<Thing, SomeContext> PARSER = new ConstructingObjectParser<>("thing",
a -> new Thing((String) a[0], (String) a[1], (Integer) a[2]));
static {
PARSER.declareString(constructorArg(), new ParseField("animal"));
PARSER.declareString(constructorArg(), new ParseField("vegetable"));
PARSER.declareInt(optionalConstructorArg(), new ParseField("mineral"));
PARSER.declareInt(Thing::setFruit, new ParseField("fruit"));
PARSER.declareInt(Thing::setBug, new ParseField("bug"));
}
This does add some overhead compared to just using ObjectParser directly. On a 2.2 GHz Intel Core i7 MacBook Air running on
battery power in a reasonably unscientific microbenchmark it is about 100 microseconds for a reasonably large object, less if the
constructor arguments are first. On this platform with the same microbenchmarks just creating the XContentParser is around 900
microseconds and using {#linkplain ObjectParser} directly adds another 300 or so microseconds. In the best case
ConstructingObjectParser allocates two additional objects per parse compared to {#linkplain ObjectParser}. In the worst case
it allocates 3 + 2 * param_count objects per parse. If this overhead is too much for you then feel free to have ObjectParser
parse a secondary object and have that one call the target object's constructor. That ought to be rare though.
Note: if optional constructor arguments aren't specified then the number of allocations is always the worst case.
AbstractObjectParser.ContextParser<Context,T>, AbstractObjectParser.NoContextParser<T>| Constructor and Description |
|---|
ConstructingObjectParser(java.lang.String name,
java.util.function.Function<java.lang.Object[],Value> builder)
Build the parser.
|
| Modifier and Type | Method and Description |
|---|---|
Value |
apply(XContentParser parser,
Context context)
Call this to do the actual parsing.
|
static <Value,FieldT> |
constructorArg()
Pass the BiConsumer this returns the declare methods to declare a required constructor argument.
|
<T> void |
declareField(java.util.function.BiConsumer<Value,T> consumer,
AbstractObjectParser.ContextParser<Context,T> parser,
ParseField parseField,
ObjectParser.ValueType type)
Declare some field.
|
static <Value,FieldT> |
optionalConstructorArg()
Pass the BiConsumer this returns the declare methods to declare an optional constructor argument.
|
declareBoolean, declareDouble, declareDoubleArray, declareField, declareFloat, declareFloatArray, declareInt, declareIntArray, declareLong, declareLongArray, declareObject, declareObjectArray, declareRawObject, declareString, declareStringArray, declareStringOrNullpublic ConstructingObjectParser(java.lang.String name,
java.util.function.Function<java.lang.Object[],Value> builder)
name - The name given to the delegate ObjectParser for error identification. Use what you'd use if the object worked with
ObjectParser.builder - A function that builds the object from an array of Objects. Declare this inline with the parser, casting the elements
of the array to the arguments so they work with your favorite constructor. The objects in the array will be in the same order
that you declared the {constructorArg()s and none will be null. If any of the constructor arguments aren't defined in
the XContent then parsing will throw an error. We use an array here rather than a Map<String, Object> to save on
allocations.public Value apply(XContentParser parser, Context context)
BiFunction for conveniently integrating with ObjectParser.public static <Value,FieldT> java.util.function.BiConsumer<Value,FieldT> constructorArg()
builder and the order that missing arguments are reported to the user if any are missing. When all of these parameters are
parsed from the XContentParser the target object is immediately built.public static <Value,FieldT> java.util.function.BiConsumer<Value,FieldT> optionalConstructorArg()
builder and the order that missing arguments are reported to the user if any are missing. When all of these parameters are
parsed from the XContentParser the target object is immediately built.public <T> void declareField(java.util.function.BiConsumer<Value,T> consumer, AbstractObjectParser.ContextParser<Context,T> parser, ParseField parseField, ObjectParser.ValueType type)
AbstractObjectParserAbstractObjectParser.declareString(BiConsumer, ParseField) or
AbstractObjectParser.declareObject(BiConsumer, BiFunction, ParseField) rather than call this directly.declareField in class AbstractObjectParser<Value,Context extends ParseFieldMatcherSupplier>