feat: Introduce Value and Record mapping to custom object types

Please note that this is a [feature preview](https://github.com/neo4j/neo4j-java-driver/blob/5.0/README.md#preview-features).

This update brings support for mapping `org.neo4j.driver.Value` and `org.neo4j.driver.Record` to custom object types.

In addition, it is also possible to map `org.neo4j.driver.Value` to already supported basic types using the new API. A limited support for mapping `org.neo4j.driver.types.TypeSystem#DURATION` to `java.time.Period` and `java.time.Duration` has also been added.

The following new method has been introduced to `org.neo4j.driver.Value`:
```java
<T> T as(Class<T> targetClass)
```

It maps the value to the given type providing that is it supported.

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

| Value Type | Supported Target Types |
|-|-|
| `TypeSystem#BOOLEAN` | `boolean`, `Boolean` |
| `TypeSystem#BYTES` | `byte[]` |
| `TypeSystem#STRING` | `String` |
| `TypeSystem#INTEGER` | `long`, `Long`, `int`, `Integer`, `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`, `java.time.Period` (only when `seconds = 0` and `nanoseconds = 0` and no overflow happens), `java.time.Duration` (only when `months = 0` and `days = 0` and no overflow happens) |
| `TypeSystem#NULL` | `null` |
| `TypeSystem#LIST` | `List` |
| `TypeSystem#MAP` | `Map` |
| `TypeSystem#NODE` | `Node` |
| `TypeSystem#RELATIONSHIP` | `Relationship` |

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](https://github.com/neo4j-graph-examples/movies)):
```java
// 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 `org.neo4j.driver.types.MapAccessor`.
If Object Graph Mapping (OGM) is needed, please use a higher level solution built on top of the driver, like
[Spring Data Neo4j](https://neo4j.com/docs/getting-started/languages-guides/java/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 `org.neo4j.driver.mapping.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 `org.neo4j.driver.mapping.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):
- Maximum matching properties.
- Minimum mismatching properties.

The constructor search is done in the order defined by the `java.lang.Class#getDeclaredConstructors` and is
finished either when a full match is found with no mismatches or 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.

Example with optional property (using the [Neo4j Movies Database](https://github.com/neo4j-graph-examples/movies)):
```java
// 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](https://github.com/neo4j-graph-examples/movies)):
```java
// 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:
```java
public record Acted<T>(List<T> roles) {}
```
Wildcard type value is not supported.

The following new method has been introduced to `org.neo4j.driver.Record`:
```java
<T> T as(Class<T> targetClass)
```

It maps values of this record to properties of the given type providing that is it supported.

Example (using the [Neo4j Movies Database](https://github.com/neo4j-graph-examples/movies)):
```java
// assuming the following Java record
public record MovieInfo(String title, String director, List<String> actors) {}
// the record values may be mapped to MovieInfo instances
var movies = driver.executableQuery("MATCH (actor:Person)-[:ACTED_IN]->(movie:Movie)<-[:DIRECTED]-(director:Person) RETURN movie.title as title, director.name AS director, collect(actor.name) Ators")
        .execute()
        .records()
        .stream()
        .map(record -> record.as(MovieInfo.class))
        .toList();
}
```

It follows the same set of rules and has the same requirements as described in the `Object Mapping` `Value` section above.

Author: injectives

driver/clirr-ignored-differences.xml

@@ -633,4 +633,16 @@
         <method>org.neo4j.driver.net.ServerAddress of(java.lang.String)</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/Value</className>
+        <differenceType>7012</differenceType>
+        <method>java.lang.Object as(java.lang.Class)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Record</className>
+        <differenceType>7012</differenceType>
+        <method>java.lang.Object as(java.lang.Class)</method>
+    </difference>
+
 </differences>

driver/src/main/java/module-info.java

@@ -29,6 +29,7 @@
     exports org.neo4j.driver.util;
     exports org.neo4j.driver.exceptions;
     exports org.neo4j.driver.exceptions.value;
+    exports org.neo4j.driver.mapping;
 
     requires org.neo4j.bolt.connection;
     requires org.neo4j.bolt.connection.netty;

driver/src/main/java/org/neo4j/driver/Record.java

@@ -19,9 +19,14 @@
 import java.util.List;
 import org.neo4j.driver.exceptions.ClientException;
 import org.neo4j.driver.exceptions.NoSuchRecordException;
+import org.neo4j.driver.exceptions.value.LossyCoercion;
+import org.neo4j.driver.exceptions.value.Uncoercible;
+import org.neo4j.driver.mapping.Property;
+import org.neo4j.driver.types.MapAccessor;
 import org.neo4j.driver.types.MapAccessorWithDefaultValue;
 import org.neo4j.driver.util.Immutable;
 import org.neo4j.driver.util.Pair;
+import org.neo4j.driver.util.Preview;
 
 /**
  * Container for Cypher result values.
@@ -78,4 +83,75 @@ public interface Record extends MapAccessorWithDefaultValue {
      * @throws NoSuchRecordException if the associated underlying record is not available
      */
     List<Pair<String, Value>> fields();
+
+    /**
+     * Maps values of this record to properties of the given type providing that is it supported.
+     * <p>
+     * Example (using the <a href=https://github.com/neo4j-graph-examples/movies>Neo4j Movies Database</a>):
+     * <pre>
+     * {@code
+     * // assuming the following Java record
+     * public record MovieInfo(String title, String director, List<String> actors) {}
+     * // the record values may be mapped to MovieInfo instances
+     * var movies = driver.executableQuery("MATCH (actor:Person)-[:ACTED_IN]->(movie:Movie)<-[:DIRECTED]-(director:Person) RETURN movie.title as title, director.name AS director, collect(actor.name) AS actors")
+     *         .execute()
+     *         .records()
+     *         .stream()
+     *         .map(record -> record.as(MovieInfo.class))
+     *         .toList();
+     * }
+     * </pre>
+     * <p>
+     * Note that Object Mapping is an alternative to accessing the user-defined values in a {@link MapAccessor}.
+     * If Object Graph Mapping (OGM) is needed, please use a higher level solution built on top of the driver, like
+     * <a href="https://neo4j.com/docs/getting-started/languages-guides/java/spring-data-neo4j/">Spring Data Neo4j</a>.
+     * <p>
+     * The mapping is done by matching user-defined property names to target type constructor parameters. Therefore, the
+     * constructor parameters must either have {@link 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 {@code -parameters} option is used or they belong to the cannonical constructor of
+     * {@link java.lang.Record java.lang.Record}). The name matching is case-sensitive.
+     * <p>
+     * Additionally, the {@link Property} annotation may be used when mapping a property with a different name to
+     * {@link java.lang.Record java.lang.Record} cannonical constructor parameter.
+     * <p>
+     * The constructor selection criteria is the following (top priority first):
+     * <ol>
+     *     <li>Maximum matching properties.</li>
+     *     <li>Minimum mismatching properties.</li>
+     * </ol>
+     * The constructor search is done in the order defined by the {@link Class#getDeclaredConstructors} and is
+     * finished either when a full match is found with no mismatches or once all constructors have been visited.
+     * <p>
+     * At least 1 property match must be present for mapping to work.
+     * <p>
+     * A {@code null} value is used for arguments that don't have a matching property. If the argument does not accept
+     * {@code null} value (this includes primitive types), an alternative constructor that excludes it must be
+     * available.
+     * <p>
+     * Types with generic parameters defined at the class level are not supported. However, constructor arguments with
+     * specific types are permitted, see the {@code actors} parameter in the example above.
+     * <p>
+     * On the contrary, the following record would not be mapped because the type information is insufficient:
+     * <pre>
+     * {@code
+     * public record MovieInfo(String title, String director, List<T> actors) {}
+     * }
+     * </pre>
+     * Wildcard type value is not supported.
+     *
+     * @param targetClass the target class to map to
+     * @param <T>         the target type to map to
+     * @return the mapped value
+     * @throws Uncoercible when mapping to the target type is not possible
+     * @throws LossyCoercion when mapping cannot be achieved without losing precision
+     * @see Property
+     * @see Value#as(Class)
+     * @since 5.28.5
+     */
+    @Preview(name = "Object mapping")
+    default <T> T as(Class<T> targetClass) {
+        // for backwards compatibility only
+        throw new UnsupportedOperationException("not supported");
+    }
 }