feat(object-mapping): Add support for mapping java.lang.Record to value

[injectives]

Please note that this is a feature preview.

This update adds support for mapping java.lang.Record to map value that may be useful when writing data to Neo4j.

The following new method has been added to org.neo4j.driver.Values:

Value value(java.lang.Record record)

It returns a map value based on record components of a given java.lang.Record.

Example (similar to the Neo4j Movies Database):

// assuming the following Java record
public record Movie(String title, String tagline, long released) {}
// a new movie may be created in the following way
var movie = new Movie("title", "tagline", 2025);
var movieValue = Values.value(movie);
driver.executableQuery("CREATE (:Movie $movie)")
         .withParameters(Map.of("movie", movieValue))
         .execute();

Because the driver methods accepting a Map<String, Object> as query parameters automatically map values to value instances, it is possible to avoid mapping movie explicitly:

var movie = new Movie("title", "tagline", 2025);
driver.executableQuery("CREATE (:Movie $movie)")
         .withParameters(Map.of("movie", movie))
         .execute();

Assuming movie titles being unique, it is possible to update the created movie in the following way:

var updatedMovie = new Movie("title", "updated tagline", 2024);
driver.executableQuery("""
                 MATCH (movie:Movie {title: $movie.title})
                 SET movie += $movie
                 """)
         .withParameters(Map.of("movie", updatedMovie))
         .execute();

The Property annotation may be used to override the record component name.

public record Movie(String title, String tagline, @Property("releasedYear") long released) {}

Note that those record components that have null value will be excluded from the map value.

It is also important to understand that sending all properties over network may not always be desirable and will depend on a use-case.

This new mapping as also available via the Value value(Object value) method, but with a note that it is still in preview status, not GA status.

[MaxAake]

✅ Very nice addition!