com.datastax.driver.dse.serde.Node Maven / Gradle / Ivy
/*
* Copyright (C) 2012-2016 DataStax Inc.
*
* This software can be used solely with DataStax Enterprise. Please consult the license at
* http://www.datastax.com/terms/datastax-dse-driver-license-terms
*/
package com.datastax.driver.dse.serde;
import com.datastax.driver.core.exceptions.DriverException;
import com.google.common.reflect.TypeToken;
import java.util.Iterator;
import java.util.Map;
/**
* A node in a tree-like structure, represented in a generic way.
*
* This interface provide convenience methods to convert the node
* that it represents into more specific types, such as
* primitive types (boolean, string, int, long, double);
* it also contains two generic
* methods: {@link #as(Class)} and {@link #as(TypeToken)} that
* can convert this node into any arbitrary Java type, provided
* that the underlying serialization runtime has been correctly configured
* to support the requested conversion.
*/
public interface Node {
/**
* Returns whether this node is {@code null}.
*
* @return {@code true} if this node is {@code null}, {@code false} otherwise.
*/
boolean isNull();
/**
* Returns whether this node is an object.
*
* Only one method out of {@link #isObject()}, {@link #isArray()} and
* {@link #isValue()} should ever return {@code true} for one given node.
*
* @return {@code true} if this node is an object, {@code false} otherwise.
*/
boolean isObject();
/**
* Returns whether this node is an array.
*
* Only one method out of {@link #isObject()}, {@link #isArray()} and
* {@link #isValue()} should ever return {@code true} for one given node.
*
* @return {@code true} if this node is an array, {@code false} otherwise.
*/
boolean isArray();
/**
* Returns whether this node is a simple value,
* i.e. either a string, a boolean, a number, or {@code null}.
*
* Only one method out of {@link #isObject()}, {@link #isArray()} and
* {@link #isValue()} should ever return {@code true} for one given node.
*
* @return whether this node is a simple value, {@code false} otherwise.
*/
boolean isValue();
/**
* Returns all the field names of the current node, if it is an object,
* or an empty iterator otherwise.
*
* @return a {@link Iterator} of all the field names of the current node.
*/
Iterator fieldNames();
/**
* Returns the size of the current node,
* if it is an array, or {@code 0} otherwise.
*
* @return the size of the current node f it is an array,
* or {@code 0} otherwise.
*/
int size();
/**
* Returns this node as an integer.
*
* If this node can not be converted to an int
* (including structured types like Objects and Arrays),
* {@code 0} will be returned; no exceptions will be thrown.
*
* @return an integer representation of this node,
* or {@code 0} if this node can not be converted to an int.
*/
int asInt();
/**
* Returns this node as a boolean.
*
* If this node can not be converted to a boolean
* (including structured types like Objects and Arrays),
* {@code false} will be returned; no exceptions will be thrown.
*
* @return a boolean representation of this node,
* or {@code false} if this node can not be converted to a boolean.
*/
boolean asBoolean();
/**
* Returns this node as a long integer.
*
* @return a long integer representation of this node,
* or {@code 0L} if this node is {@code null}.
*/
long asLong();
/**
* Returns this node as a double.
*
* @return a double representation of this node,
* or {@code 0.0D} if this node is {@code null}.
*/
double asDouble();
/**
* Returns a valid String representation of this node,
* if the node is a simple node (i.e. it is not an object nor an array),
* otherwise returns an empty String.
*
* @return a String representation of this node,
* or an empty string, if this node is not a simple node.
*/
String asString();
/**
* Deserializes and returns this node as an instance of {@code Map}.
*
* @return this node converted into an instance of {@code Map}.
* @throws DriverException if this node cannot be converted to a map.
*/
Map asMap();
/**
* Deserializes and returns this node as an instance of {@code clazz}.
*
* Before attempting such a conversion, there must be an appropriate converter
* configured on the underlying serialization runtime.
*
* @param clazz the class to convert this node into.
* @return this node converted into an instance of {@code clazz}.
* @throws DriverException if this node cannot be converted to the given class.
*/
T as(Class clazz);
/**
* Deserializes and returns this node as an instance of the given {@link TypeToken type}.
*
* Before attempting such a conversion, there must be an appropriate converter
* configured on the underlying serialization runtime.
*
* @param type the type to convert this node into.
* @return this node converted into an instance of {@code type}.
* @throws DriverException if this node cannot be converted to the given type.
*/
T as(TypeToken type);
/**
* Returns the value of the specified field of an object node.
*
* If this node is not an object (or it does not have a value
* for the specified field name), or if there is no field with
* such name, {@code null} is returned.
*
* If the property value has been explicitly set to {@code null},
* implementors may return a special "null node" instead of {@code null}.
*
* @param fieldName the field name to fetch.
* @return a node containing the requested field value, or {@code null}
* if it does not exist.
*/
Node get(String fieldName);
/**
* Returns the element node at the specified {@code index} of an array node.
*
* For all other node types, {@code null} is returned.
*
* If {@code index} is out of bounds, (i.e. less than zero or {@code >= size()},
* {@code null} is returned; no exception will be thrown.
*
* If the requested element has been explicitly set to {@code null},
* implementors may return a special "null node" instead of {@code null}.
*
* @param index the element index to fetch.
* @return a node containing the requested element, or {@code null}
* if it does not exist.
*/
Node get(int index);
}