com.yahoo.slime.Inspector Maven / Gradle / Ivy
// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.slime;
import java.util.function.Consumer;
/**
* Interface for read-only access to any value or object that is part
* of a Slime. You can access meta-data such as validity and actual
* type. You can always convert to any basic type by calling the
* various "as" accessor methods; these return a default value if the
* current Inspector is invalid or the type doesn't match your
* accessor type. If you want to do something exceptional instead
* when the types don't match, you must check using type() first.
*
* @author havardpe
*/
public interface Inspector {
/** check if this inspector is valid */
boolean valid();
/** Invoke the given consumer with this value if it is valid */
void ifValid(Consumer consumer);
/** return an enum describing value type */
Type type();
/**
* Check how many entries or fields are contained in the current value.
* Useful for arrays and objects; anything else always returns 0.
* @return number of entries/fields contained.
*/
int children();
/**
* Check how many entries are contained in the current value.
* Useful for arrays; anything else always returns 0.
* @return number of entries contained.
*/
int entries();
/**
* Check how many fields are contained in the current value.
* Useful for objects; anything else always returns 0.
* @return number of fields contained.
*/
int fields();
/** the current value (for booleans); default: false */
boolean asBool();
/** the current value (for integers); default: 0 */
long asLong();
/** the current value (for floating-point values); default: 0.0 */
double asDouble();
/** the current value (for string values); default: empty string */
String asString();
/** the current value encoded into UTF-8 (for string values); default: empty array */
byte[] asUtf8();
/** the current value (for data values); default: empty array */
byte[] asData();
/**
* Use the visitor pattern to resolve the underlying type of this value.
* @param v the visitor
*/
void accept(Visitor v);
/**
* Traverse an array value, performing callbacks for each entry.
*
* If the current Inspector is connected to an array value,
* perform callbacks to the given traverser for each entry
* contained in the array.
* @param at traverser callback object.
*/
@SuppressWarnings("overloads")
void traverse(ArrayTraverser at);
/**
* Traverse an object value, performing callbacks for each field.
*
* If the current Inspector is connected to an object value,
* perform callbacks to the given traverser for each field
* contained in the object.
* @param ot traverser callback object.
*/
@SuppressWarnings("overloads")
void traverse(ObjectSymbolTraverser ot);
/**
* Traverse an object value, performing callbacks for each field.
*
* If the current Inspector is connected to an object value,
* perform callbacks to the given traverser for each field
* contained in the object.
* @param ot traverser callback object.
*/
@SuppressWarnings("overloads")
void traverse(ObjectTraverser ot);
/**
* Access an array entry.
*
* If the current Inspector doesn't connect to an array value,
* or the given array index is out of bounds, the returned
* Inspector will be invalid.
* @param idx array index.
* @return a new Inspector for the entry value.
*/
Inspector entry(int idx);
/**
* Access a field in an object by symbol id.
*
* If the current Inspector doesn't connect to an object value, or
* the object value does not contain a field with the given symbol
* id, the returned Inspector will be invalid.
* @param sym symbol id.
* @return a new Inspector for the field value.
*/
Inspector field(int sym);
/**
* Access a field in an object by symbol name.
*
* If the current Inspector doesn't connect to an object value, or
* the object value does not contain a field with the given symbol
* name, the returned Inspector will be invalid.
* @param name symbol name.
* @return a new Inspector for the field value.
*/
Inspector field(String name);
/**
* Tests whether this is equal to Inspector.
*
* Since equality of two Inspectors is subtle, {@link Object#equals(Object)} is not used.
*
* @param that inspector.
* @return true if they are equal.
*/
default boolean equalTo(Inspector that) { return SlimeUtils.equalTo(this, that); }
}