Module org.neo4j.driver

Package org.neo4j.driver.internal.value

Class MapValue

java.lang.Object

org.neo4j.driver.internal.types.InternalMapAccessorWithDefaultValue

org.neo4j.driver.internal.value.ValueAdapter

org.neo4j.driver.internal.value.MapValue

All Implemented Interfaces:

org.neo4j.bolt.connection.values.Value, org.neo4j.driver.internal.AsValue, InternalValue, MapAccessor, MapAccessorWithDefaultValue, Value

public class MapValue
extends ValueAdapter

Constructor Summary

Constructors

Constructor	Description
MapValue(Map<String,Value> val)

Method Summary

Modifier and Type	Method	Description
<T> T	as(Class<T> targetClass)	Maps this value to the given type providing that is it supported.
Object	as(ParameterizedType type)
Map<String,org.neo4j.bolt.connection.values.Value>	asBoltMap()
Map<String,Object>	asMap()	Return the underlying map as a map of string keys and values converted using Value.asObject().
<T> Map<String,T>	asMap(Function<Value,T> mapFunction)	Return the underlying map as a map of string keys and values converted using the supplied function.
Map<String,Object>	asObject()	This returns a java standard library representation of the underlying value, using a java type that is "sensible" given the underlying type.
org.neo4j.bolt.connection.values.Type	boltValueType()
boolean	containsKey(String key)	Check if the list of keys contains the given key
boolean	equals(Object o)
Value	get(String key)	Retrieve the value of the property with the given key
int	hashCode()
boolean	isEmpty()	If this value represents a list or map, test if the collection is empty.
Iterable<String>	keys()	If the underlying value supports key-based indexing, return an iterable of the keys in the map, this applies to map, node and TypeSystem.RELATIONSHIP() relationship} values.
int	size()	If the underlying value is a collection type, return the number of values in the collection.
String	toString()
Type	type()	Returns the type of this value as defined in the Neo4j type system.
Iterable<Value>	values()	Retrieve all values of the underlying collection
<T> Iterable<T>	values(Function<Value,T> mapFunction)	Map and retrieve all values of the underlying collection

Methods inherited from class org.neo4j.driver.internal.value.ValueAdapter

asBoltVector, asBoolean, asBoolean, asByteArray, asByteArray, asDouble, asDouble, asEntity, asFloat, asFloat, asInt, asInt, asIsoDuration, asIsoDuration, asList, asList, asList, asList, asLocalDate, asLocalDate, asLocalDateTime, asLocalDateTime, asLocalTime, asLocalTime, asLong, asLong, asMap, asMap, asMapped, asNode, asNumber, asOffsetDateTime, asOffsetDateTime, asOffsetTime, asOffsetTime, asPath, asPoint, asPoint, asRelationship, asString, asString, asUnsupportedType, asValue, asVector, asZonedDateTime, asZonedDateTime, computeOrDefault, get, hasType, isFalse, isNull, isTrue, typeConstructor

Methods inherited from class org.neo4j.driver.internal.types.InternalMapAccessorWithDefaultValue

get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.neo4j.driver.internal.value.InternalValue

as, asBoltIsoDuration, asBoltPoint, boltValues, getBoltValue

Methods inherited from interface org.neo4j.driver.types.MapAccessorWithDefaultValue

get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get

Constructor Details

MapValue

public MapValue(Map<String,Value> val)

Method Details

isEmpty

public boolean isEmpty()

Description copied from interface: Value

If this value represents a list or map, test if the collection is empty.

Specified by:

isEmpty in interface org.neo4j.bolt.connection.values.Value

Specified by:

isEmpty in interface Value

Overrides:

isEmpty in class ValueAdapter

Returns:

true if size() is 0, otherwise false

asObject

public Map<String,Object> asObject()

Description copied from interface: Value

This returns a java standard library representation of the underlying value, using a java type that is "sensible" given the underlying type. The mapping for common types is as follows:

• TypeSystem.NULL() - null
• TypeSystem.LIST() - List
• TypeSystem.MAP() - Map
• TypeSystem.BOOLEAN() - Boolean
• TypeSystem.INTEGER() - Long
• TypeSystem.FLOAT() - Double
• TypeSystem.STRING() - String
• TypeSystem.BYTES() - byte[]
• TypeSystem.DATE() - LocalDate
• TypeSystem.TIME() - OffsetTime
• TypeSystem.LOCAL_TIME() - LocalTime
• TypeSystem.DATE_TIME() - ZonedDateTime
• TypeSystem.LOCAL_DATE_TIME() - LocalDateTime
• TypeSystem.DURATION() - IsoDuration
• TypeSystem.POINT() - Point
• TypeSystem.NODE() - Node
• TypeSystem.RELATIONSHIP() - Relationship
• TypeSystem.PATH() - Path

Note that the types in TypeSystem refers to the Neo4j type system where TypeSystem.INTEGER() and TypeSystem.FLOAT() are both 64-bit precision. This is why these types return java Long and Double, respectively.

Specified by:

asObject in interface Value

Overrides:

asObject in class ValueAdapter

Returns:

the value as a Java Object.

as

public <T> T as(Class<T> targetClass)

Description copied from interface: Value

Maps this value to the given type providing that is it supported.

Basic Mapping

Supported destination types depend on the value Type, please see the table below for more details.

Supported Mappings

Value Type	Supported Target Types
TypeSystem.BOOLEAN()	boolean, Boolean
TypeSystem.BYTES()	byte[]
TypeSystem.STRING()	String, char, Character
TypeSystem.INTEGER()	long, Long, int, Integer, short, Short, double, Double, float, Float
TypeSystem.FLOAT()	long, Long, int, Integer, double, Double, float, Float
TypeSystem.PATH()	Path
TypeSystem.POINT()	Point
TypeSystem.DATE()	LocalDate
TypeSystem.TIME()	OffsetTime
TypeSystem.LOCAL_TIME()	LocalTime
TypeSystem.LOCAL_DATE_TIME()	LocalDateTime
TypeSystem.DATE_TIME()	ZonedDateTime, OffsetDateTime
TypeSystem.DURATION()	IsoDuration, Period (only when seconds = 0 and nanoseconds = 0 and no overflow happens), Duration (only when months = 0 and days = 0 and no overflow happens)
TypeSystem.NULL()	null
TypeSystem.LIST()	List, T[] as long as list elements may be mapped to the array component type (for example, char[], boolean[], String[], long[], int[], short[], double[], float[])
TypeSystem.MAP()	Map
TypeSystem.NODE()	Node
TypeSystem.RELATIONSHIP()	Relationship
TypeSystem.VECTOR()	Vector
TypeSystem.UNSUPPORTED()	UnsupportedType

Object Mapping

Mapping of user-defined properties to user-defined types is supported for the following value types:

• TypeSystem.NODE()
• TypeSystem.RELATIONSHIP()
• TypeSystem.MAP()

Example (using the Neo4j Movies Database):

 
 // assuming the following Java record
 public record Movie(String title, String tagline, long released) {}
 // the nodes may be mapped to Movie instances
 var movies = driver.executableQuery("MATCH (movie:Movie) RETURN movie")
         .execute()
         .records()
         .stream()
         .map(record -> record.get("movie").as(Movie.class))
         .toList();
 
 

Note that Object Mapping is an alternative to accessing the user-defined values in a MapAccessor. If Object Graph Mapping (OGM) is needed, please use a higher level solution built on top of the driver, like Spring Data Neo4j.

The mapping is done by matching user-defined property names to target type constructor parameters. Therefore, the constructor parameters must either have Property annotation or have a matching name that is available at runtime (note that the constructor parameter names are typically changed by the compiler unless either the compiler -parameters option is used or they belong to the cannonical constructor of java.lang.Record). The name matching is case-sensitive.

Additionally, the Property annotation may be used when mapping a property with a different name to java.lang.Record cannonical constructor parameter.

The constructor selection criteria is the following (top priority first):

1. Maximum matching properties.
2. Minimum mismatching properties.

The constructor search is done in the order defined by the Class.getDeclaredConstructors().

Only constructors that are accessible or can be made accessible using AccessibleObject.trySetAccessible() are included in the search. If multiple constructors have the same number of matching and mismatching properties, the first constructor that is accessible by default is selected.

The search finishes as soon as a constructor that is accessible by default and matches all properties is found. Otherwise, it finishes once all constructors have been visited.

At least 1 property match must be present for mapping to work.

A null value is used for arguments that don't have a matching property. If the argument does not accept null value (this includes primitive types), an alternative constructor that excludes it must be available.

The mapping only works for types with directly accessible constructors, not interfaces or abstract types.

Example with optional property (using the Neo4j Movies Database):

 
 // assuming the following Java record
 public record Person(String name, long born) {
     // alternative constructor for values that don't have 'born' property available
     public Person(@Property("name") String name) {
         this(name, -1);
     }
 }
 // the nodes may be mapped to Person instances
 var persons = driver.executableQuery("MATCH (person:Person) RETURN person")
         .execute()
         .records()
         .stream()
         .map(record -> record.get("person").as(Person.class))
         .toList();
 
 

Types with generic parameters defined at the class level are not supported. However, constructor arguments with specific types are permitted.

Example (using the Neo4j Movies Database):

 
 // assuming the following Java record
 public record Acted(List<String> roles) {}
 // the relationships may be mapped to Acted instances
 var actedList = driver.executableQuery("MATCH ()-[acted:ACTED_IN]-() RETURN acted")
         .execute()
         .records()
         .stream()
         .map(record -> record.get("acted").as(Acted.class))
         .toList();
 
 

On the contrary, the following record would not be mapped because the type information is insufficient:

 
 public record Acted<T>(List<T> roles) {}
 
 

Wildcard type value is not supported.

Type Parameters:

T - the target type to map to

Parameters:

targetClass - the target class to map to

Returns:

the mapped value

See Also:

• Property

as

public Object as(ParameterizedType type)

asMap

public Map<String,Object> asMap()

Description copied from interface: MapAccessor

Return the underlying map as a map of string keys and values converted using Value.asObject().

This is equivalent to calling MapAccessor.asMap(Function) with Values.ofObject().

Specified by:

asMap in interface MapAccessor

Overrides:

asMap in class ValueAdapter

Returns:

the value as a Java map

asMap

public <T> Map<String,T> asMap(Function<Value,T> mapFunction)

Description copied from interface: MapAccessor

Return the underlying map as a map of string keys and values converted using the supplied function.

Specified by:

asMap in interface MapAccessor

Overrides:

asMap in class ValueAdapter

Type Parameters:

T - the type of map values

Parameters:

mapFunction - a function to map from Value to T. See Values for some predefined functions, such as Values.ofBoolean(), Values.ofList(Function).

Returns:

the value as a map from string keys to values of type T obtained from mapping the original map values, if possible

See Also:

• for a long list of built-in conversion functions

size

public int size()

Description copied from interface: Value

If the underlying value is a collection type, return the number of values in the collection.

For TypeSystem.LIST() list} values, this will return the size of the list.

For map values, this will return the number of entries in the map.

For node and TypeSystem.RELATIONSHIP() relationship} values, this will return the number of properties.

For path values, this returns the length (number of relationships) in the path.

Specified by:

size in interface MapAccessor

Specified by:

size in interface Value

Overrides:

size in class ValueAdapter

Returns:

the number of values in an underlying collection

containsKey

public boolean containsKey(String key)

Description copied from interface: MapAccessor

Check if the list of keys contains the given key

Specified by:

containsKey in interface MapAccessor

Overrides:

containsKey in class ValueAdapter

Parameters:

key - the key

Returns:

true if this map keys contains the given key otherwise false

keys

public Iterable<String> keys()

Description copied from interface: Value

If the underlying value supports key-based indexing, return an iterable of the keys in the map, this applies to map, node and TypeSystem.RELATIONSHIP() relationship} values.

Specified by:

keys in interface MapAccessor

Specified by:

keys in interface Value

Overrides:

keys in class ValueAdapter

Returns:

the keys in the value

values

public Iterable<Value> values()

Description copied from interface: MapAccessor

Retrieve all values of the underlying collection

Specified by:

values in interface MapAccessor

Overrides:

values in class ValueAdapter

Returns:

all values in unspecified order

values

public <T> Iterable<T> values(Function<Value,T> mapFunction)

Description copied from interface: MapAccessor

Map and retrieve all values of the underlying collection

Specified by:

values in interface MapAccessor

Overrides:

values in class ValueAdapter

Type Parameters:

T - the target type of mapping

Parameters:

mapFunction - a function to map from Value to T. See Values for some predefined functions, such as Values.ofBoolean(), Values.ofList(Function).

Returns:

the result of mapping all values in unspecified order

get

public Value get(String key)

Description copied from interface: MapAccessor

Retrieve the value of the property with the given key

Specified by:

get in interface MapAccessor

Overrides:

get in class ValueAdapter

Parameters:

key - the key of the property

Returns:

the property's value or a NullValue if no such key exists

toString

public String toString()

Specified by:

toString in interface Value

Specified by:

toString in class ValueAdapter

type

public Type type()

Description copied from interface: Value

Returns the type of this value as defined in the Neo4j type system.

Returns:

the type of this value as defined in the Neo4j type system

boltValueType

public org.neo4j.bolt.connection.values.Type boltValueType()

asBoltMap

public Map<String,org.neo4j.bolt.connection.values.Value> asBoltMap()

equals

public boolean equals(Object o)

Specified by:

equals in interface Value

Specified by:

equals in class ValueAdapter

hashCode

public int hashCode()

Specified by:

hashCode in interface Value

Specified by:

hashCode in class ValueAdapter