org.neo4j.driver.v1.Value Maven / Gradle / Ivy
/**
* Copyright (c) 2002-2016 "Neo Technology,"
* Network Engine for Objects in Lund AB [http://neotechnology.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.driver.v1;
import java.util.List;
import java.util.Map;
import org.neo4j.driver.v1.exceptions.value.LossyCoercion;
import org.neo4j.driver.v1.exceptions.value.Uncoercible;
/**
* Represents a value from Neo4j.
*
* This interface describes a number of isType methods along with
* typeValue methods. The first set of these correlate with types from
* the Neo4j Type System and are used to determine which Neo4j type is represented.
* The second set of methods perform coercions to Java types (wherever possible).
* For example, a common String value should be tested for using isString
* and extracted using stringValue.
*
* Navigating a tree structure
*
* Because Neo4j often handles dynamic structures, this interface is designed to help
* you handle such structures in Java. Specifically, {@link Value} lets you navigate arbitrary tree
* structures without having to resort to type casting.
*
* Given a tree structure like:
*
*
* {@code
* {
* users : [
* { name : "Anders" },
* { name : "John" }
* ]
* }
* }
*
*
* You can retrieve the name of the second user, John, like so:
*
*
* {@code
* String username = value.get("users").get(1).get("name").asString();
* }
*
*
* You can also easily iterate over the users:
*
*
* {@code
* List names = new LinkedList<>();
* for(Value user : value.get("users").values() )
* {
* names.add(user.get("name").asString());
* }
* }
*
*/
@Immutable
public interface Value extends MapAccessor, ListAccessor
{
/**
* If the underlying value is a collection type, return the number of values in the collection.
*
* For {@link TypeSystem#LIST()} list} values, this will return the size of the list.
*
* For {@link TypeSystem#MAP() map} values, this will return the number of entries in the map.
*
* For {@link TypeSystem#NODE() node} and {@link TypeSystem#RELATIONSHIP()} relationship} values,
* this will return the number of properties.
*
* For {@link TypeSystem#PATH() path} values, this returns the length (number of relationships) in the path.
*
* @return the number of values in an underlying collection
*/
int size();
/**
* If this value represents a list or map, test if the collection is empty.
*
* @return true if size() is 0, otherwise false
*/
boolean isEmpty();
/**
* If the underlying value supports {@link #get(String) key-based indexing}, return an iterable of the keys in the
* map, this applies to {@link TypeSystem#MAP() map}, {@link #asNode() node} and {@link
* TypeSystem#RELATIONSHIP()} relationship} values.
*
* @return the keys in the value
*/
@Override
Iterable keys();
/** @return The type of this value as defined in the Neo4j type system */
@Experimental
Type type();
/**
* Test if this value is a value of the given type
*
* @param type the given type
* @return type.isTypeOf( this )
*/
@Experimental
boolean hasType( Type type );
/**
* @return true if the value is a Boolean value and has the value True.
*/
boolean isTrue();
/**
* @return true if the value is a Boolean value and has the value False.
*/
boolean isFalse();
/**
* @return true if the value is a Null, otherwise false
*/
boolean isNull();
/**
* This returns a java standard library representation of the underlying value,
* using a java type that is "sensible" given the underlying type. For instance,
* a Neo4j List will return a Java {@code List