com.yahoo.data.access.Inspector Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of vespajlib Show documentation
Library for use in Java components of Vespa. Shared code which do not fit anywhere else.
There is a newer version: 8.441.21
// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.data.access;


import java.util.Map;

/**
 * This is a generic API for accessing structured, generic, schemaless data.
 * An inspector is a handle to a value that has one of 8 specific types:
 * EMPTY, the 5 scalar types BOOL, LONG, DOUBLE, STRING, or DATA, the
 * simple list-like ARRAY container and the struct-like OBJECT container.
 * Instrospection methods are available, but you can also use accessors
 * with a default value if you expect a certain type and just want your
 * default value if some field doesn't exist or was of the wrong type.
 * 
 * @author havardpe
 */
public interface Inspector extends Inspectable {

    /**
     * Check if the inspector is valid.
     * If you try to access a field or array entry that does not exist,
     * you will get an invalid Inspector returned.
     */
    boolean valid();

    /** Get the type of an inspector */
    Type type();

    /** Get the number of entries in an ARRAY (always returns 0 for non-arrays) */
    int entryCount();

    /** Get the number of fields in an OBJECT (always returns 0 for non-objects) */
    int fieldCount();

    /** Access the inspector's value if it's a BOOLEAN; otherwise throws exception */
    boolean asBool();

    /** Access the inspector's value if it's a LONG (or DOUBLE); otherwise throws exception */
    long asLong();

    /** Access the inspector's value if it's a DOUBLE (or LONG); otherwise throws exception */
    double asDouble();

    /** Access the inspector's value if it's a STRING; otherwise throws exception */
    String asString();

    /**
     * Access the inspector's value (in utf-8 representation) if it's
     * a STRING; otherwise throws exception
     */
    byte[] asUtf8();

    /** Access the inspector's value if it's DATA; otherwise throws exception */
    byte[] asData();

    /** Get the inspector's value (or the supplied default), never throws */
    boolean asBool(boolean defaultValue);

    /** Get the inspector's value (or the supplied default), never throws */
    long asLong(long defaultValue);

    /** Get the inspector's value (or the supplied default), never throws */
    double asDouble(double defaultValue);

    /** Get the inspector's value (or the supplied default), never throws */
    String asString(String defaultValue);

    /** Get the inspector's value (or the supplied default), never throws */
    byte[] asUtf8(byte[] defaultValue);

    /** Get the inspector's value (or the supplied default), never throws */
    byte[] asData(byte[] defaultValue);

    /**
     * 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.  Otherwise a no-op.
     * 
     * @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.  Otherwise a no-op.
     * 
     * @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 an field in an object.
     *
     * 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);

    /**
     * Convert an array to an iterable list.  Other types will just
     * return an empty list.
     */
    Iterable entries();

    /**
     * Convert an object to an iterable list of (name, value) pairs.
     * Other types will just return an empty list.
     */
    Iterable> fields();

}