BeanWrapper class

Reads and writes the properties of an object by path (address.city, tags[0]), converting written values to the property types.

It is the engine behind data binding: request parameters arrive as strings with dotted names and must land in typed fields of nested objects. Use it directly when your own code has such name-value pairs; otherwise DataBinder uses it for you.

Paths: name, address.city, tags[0], scores['math'], orders[1].items[0].sku. Written values are converted to the property type with the conversion service — also list elements and map keys and values, whose types come from the generated TypeInfo of the property (scores[3] of a Map<int, double> puts the key 3). Plain Maps can be wrapped too (keys act as properties).

With autoGrowNestedPaths, writes create what the path needs: null nested objects, lists and maps, and list elements up to the index (items[2].sku on an empty list adds three items, below autoGrowCollectionLimit).

// Fill a Person from string values, creating nested objects as needed.
final wrapper = BeanWrapper(person, autoGrowNestedPaths: true)
  ..setPropertyValue('age', '42') // converted to int
  ..setPropertyValue('address.city', 'Lyon') // creates the Address
  ..setPropertyValue('previous[1].city', 'Oslo') // grows the list
  ..setPropertyValue('tags[0]', 'admin');
wrapper.getPropertyValue('address.city'); // 'Lyon'
wrapper.getPropertyType('age'); // int

Spring (Java):

BeanWrapper wrapper = new BeanWrapperImpl(person);
wrapper.setAutoGrowNestedPaths(true);
wrapper.setPropertyValue("age", "42");
wrapper.setPropertyValue("address.city", "Lyon");
wrapper.setPropertyValue("previous[1].city", "Oslo");
wrapper.setPropertyValue("tags[0]", "admin");
wrapper.getPropertyValue("address.city");

Unlike Spring, the classes involved must be @Introspected (no reflection); without generated TypeInfo (hand-written introspections) element types are unknown and indexed values are stored as they are. Reads never grow anything.

Constructors

BeanWrapper(Object wrappedInstance, {BeanIntrospector? introspector, ConversionService? conversionService, bool autoGrowNestedPaths = false, int autoGrowCollectionLimit = 0x7FFFFFFF})

Wraps wrappedInstance; introspector defaults to BeanIntrospector.shared and conversionService to the shared DefaultConversionService.

Properties

autoGrowCollectionLimit → int

Lists are grown up to (not including) this index, like Spring's autoGrowCollectionLimit; a guard against a request asking for items[1000000]. Practically unlimited by default.

final

autoGrowNestedPaths → bool

Whether writes create what the path needs instead of failing: null nested introspected objects (with a no-argument constructor), lists and maps, and missing list elements. false by default.

final

conversionService → ConversionService

Converts written values to the property types.

final

hashCode → int

The hash code for this object.

no setter, inherited

introspector → BeanIntrospector

Where the descriptions of the classes on the path come from.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

wrappedInstance → Object

The object whose properties are accessed.

final

Methods

getPropertyType(String path) → Type?

The declared type of the property at path (for list elements and map values: the generated element type, else the runtime type of the value), or null if unknown.

getPropertyValue(String path) → Object?

The value at path; reads never grow anything.

isReadableProperty(String path) → bool

Whether path can be read: every segment exists and none before the last is null. Never throws.

isWritableProperty(String path) → bool

Whether path can be written: it ends at a writable property, at a map key, or at an index (indexes are only checked by the write itself). false when a value on the way is null. Never throws.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

setPropertyValue(String path, Object? value) → void

Writes value at path, converting it to the property type (or the element / map value type).

setPropertyValues(Map<String, Object?> values, {bool ignoreUnknown = false, bool ignoreInvalid = false}) → void

Sets every entry; failures are collected into a PropertyBatchUpdateException.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited