Add value coercion examples

examples/src/main/java/org/neo4j/docs/driver/ReadingValuesExample.java

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.neo4j.docs.driver;
+
+import java.util.function.Function;
+
+import org.neo4j.driver.Record;
+import org.neo4j.driver.Result;
+import org.neo4j.driver.Session;
+import org.neo4j.driver.Value;
+
+import static org.neo4j.driver.Values.parameters;
+
+public class ReadingValuesExample extends BaseApplication
+{
+    private static final String nullFieldName = "fieldName";
+    private static final String intFieldName = "fieldName";
+
+    public ReadingValuesExample( String uri, String user, String password )
+    {
+        super( uri, user, password );
+    }
+
+    public Boolean nullIsNull()
+    {
+        return echo( null, record ->
+        {
+            // tag::java-driver-reading-values-null[]
+            Value nullValue = record.get( nullFieldName );
+
+            // Checking if its null
+            Boolean trueBoolean = nullValue.isNull(); // true
+
+            // end::java-driver-reading-values-null[]
+            return trueBoolean;
+        } );
+    }
+
+    public String nullAsString()
+    {
+        return echo( null, record ->
+        {
+            Value nullValue = record.get( nullFieldName );
+            // tag::java-driver-reading-values-null[]
+            // Getting the null value as string
+            String stringWithNullContent = nullValue.asString(); // "null"
+
+            // end::java-driver-reading-values-null[]
+            return stringWithNullContent;
+        } );
+    }
+
+    public Object nullAsObject()
+    {
+        return echo( null, record ->
+        {
+            Value nullValue = record.get( nullFieldName );
+            // tag::java-driver-reading-values-null[]
+            // Getting `null` as object
+            Object nullObject = nullValue.asObject(); // null
+
+            // end::java-driver-reading-values-null[]
+            return nullObject;
+        } );
+    }
+
+    public float nullAsObjectFloatDefaultValue()
+    {
+        return echo( null, record ->
+        {
+            Value nullValue = record.get( nullFieldName );
+            // tag::java-driver-reading-values-null[]
+            // Coercing value with a default value set
+            float floatValue = nullValue.asFloat( 1.0f ); // 1.0f
+
+            // end::java-driver-reading-values-null[]
+            return floatValue;
+        } );
+    }
+
+    public void nullAsObjectFloat()
+    {
+        echo( null, record ->
+        {
+            Value nullValue = record.get( nullFieldName );
+            // tag::java-driver-reading-values-null[]
+            // Could not cast null to float
+            float floatValue = nullValue.asFloat(); // throws org.neo4j.driver.exceptions.value.Uncoercible
+            // end::java-driver-reading-values-null[]
+            return floatValue;
+        } );
+    }
+
+    public Boolean integerFieldIsNull()
+    {
+        return echo( 4, record ->
+        {
+            // tag::java-driver-reading-values-non-null[]
+            Value value = record.get( intFieldName );
+            // Checking if the value is null
+            Boolean falseBoolean = value.isNull(); // false
+
+            // end::java-driver-reading-values-non-null[]
+            return falseBoolean;
+        } );
+    }
+
+    public int integerAsInteger()
+    {
+        return echo( 4, record ->
+        {
+            Value value = record.get( intFieldName );
+
+            // tag::java-driver-reading-values-non-null[]
+            // Getting as int
+            int intValue = value.asInt(); // the int
+
+            // end::java-driver-reading-values-non-null[]
+            return intValue;
+        } );
+    }
+
+    public long integerAsLong()
+    {
+        return echo( 4, record ->
+        {
+            Value value = record.get( intFieldName );
+
+            // tag::java-driver-reading-values-non-null[]
+            // Getting value asLong is also possible for int values
+            long longValue = value.asLong(); // the int casted to long
+
+            // end::java-driver-reading-values-non-null[]
+            return longValue;
+        } );
+    }
+
+    public void integerAsString()
+    {
+        echo( 4, record ->
+        {
+            Value value = record.get( intFieldName );
+
+            // tag::java-driver-reading-values-non-null[]
+            // But it's not possible to get the int value as string
+            String stringValue = value.asString(); // throws org.neo4j.driver.exceptions.value.Uncoercible
+            // end::java-driver-reading-values-non-null[]
+            return stringValue;
+        } );
+    }
+
+    private <T, O> O echo( T value, Function<Record,O> transformation )
+    {
+        try ( Session session = driver.session() )
+        {
+            return session.readTransaction( tx ->
+                                            {
+                                                Result result = tx.run( "RETURN $in AS fieldName", parameters( "in", value ) );
+                                                Record record = result.next();
+                                                return transformation.apply( record );
+                                            } );
+        }
+    }
+}

examples/src/test/java/org/neo4j/docs/driver/ExamplesIT.java

@@ -38,6 +38,7 @@
 import org.neo4j.driver.SessionConfig;
 import org.neo4j.driver.Value;
 import org.neo4j.driver.Values;
+import org.neo4j.driver.exceptions.value.Uncoercible;
 import org.neo4j.driver.internal.util.EnabledOnNeo4jWith;
 import org.neo4j.driver.summary.QueryType;
 import org.neo4j.driver.summary.ResultSummary;
@@ -55,8 +56,10 @@
 import static org.hamcrest.Matchers.greaterThanOrEqualTo;
 import static org.hamcrest.Matchers.instanceOf;
 import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.nullValue;
 import static org.hamcrest.junit.MatcherAssert.assertThat;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.neo4j.driver.Config.TrustStrategy.trustAllCertificates;
 import static org.neo4j.driver.Values.parameters;
@@ -718,4 +721,22 @@ void testUseAnotherDatabaseExample() throws Exception
             assertThat( greetingCount, is( 1 ) );
         }
     }
+
+    @Test
+    void testReadingValuesExample() throws Exception
+    {
+        try (ReadingValuesExample example = new ReadingValuesExample( uri, USER, PASSWORD ))
+        {
+            assertThat( example.integerFieldIsNull(), is(false) );
+            assertThat( example.integerAsInteger(), is( 4 ) );
+            assertThat( example.integerAsLong(), is( 4L ) );
+            assertThrows( Uncoercible.class, example::integerAsString );
+
+            assertThat( example.nullIsNull(), is(true) );
+            assertThat( example.nullAsString(), is( "null" ) );
+            assertThat( example.nullAsObject(), nullValue());
+            assertThat( example.nullAsObjectFloatDefaultValue(), is( 1.0f ) );
+            assertThrows( Uncoercible.class, example::nullAsObjectFloat );
+        }
+    }
 }