com.yahoo.slime.Cursor Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of vespajlib Show documentation
Show all versions of vespajlib Show documentation
Library for use in Java components of Vespa. Shared code which do
not fit anywhere else.
// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.slime;
/**
* Interface for read-write access to any value or object that is part
* of a Slime. All accessors (including meta-data) are inherited from
* the Inspector interface. The navigational methods also work the
* same, except that they return a new Cursor for contained values and
* sub-structures, to permit writes to embedded values.
*
* The write operations are adding a new entry (to arrays), or setting
* a field value (for objects). If adding an entry or setting a field
* cannot be performed for any reason, an invalid Cursor is returned.
*
* This could happen because the current cursor is invalid, or it's
* not connected to an array value (for add methods), or it's not
* connected to an object (for set methods). Also note that you can
* only set() a field once; you cannot overwrite the field in any way.
*
* @author havardpe
*/
public interface Cursor extends Inspector {
/**
* Accesses an array entry.
*
* If the current Cursor doesn't connect to an array value,
* or the given array index is out of bounds, the returned
* Cursor will be invalid.
*
* @param idx array index
* @return a new Cursor for the entry value
*/
@Override
Cursor entry(int idx);
/**
* Accesses a field in an object by symbol id.
*
* If the current Cursor doesn't connect to an object value, or
* the object value does not contain a field with the given symbol
* id, the returned Cursor will be invalid.
*
* @param sym symbol id
* @return a new Cursor for the field value
*/
@Override
Cursor field(int sym);
/**
* Accesses a field in an object by symbol name.
*
* If the current Cursor doesn't connect to an object value, or
* the object value does not contain a field with the given symbol
* name, the returned Cursor will be invalid.
*
* @param name symbol name
* @return a new Cursor for the field value
*/
@Override
Cursor field(String name);
/**
* Appends an array entry containing a new value of NIX type.
* Returns an invalid Cursor if unsuccessful.
*
* @return a valid Cursor referencing the new entry value if successful
*/
Cursor addNix();
/**
* Appends an array entry containing a new value of BOOL type.
* Returns an invalid Cursor if unsuccessful.
*
* @param bit the actual boolean value for initializing a new BoolValue
* @return a valid Cursor referencing the new entry value if successful
*/
Cursor addBool(boolean bit);
/** Adds a new entry of LONG type to an array. */
Cursor addLong(long l);
/** Adds a new entry of DOUBLE type to an array. */
Cursor addDouble(double d);
/** Add a new entry of STRING type to an array. */
Cursor addString(String str);
/** Add a new entry of STRING type to an array. */
Cursor addString(byte[] utf8);
/** Add a new entry of DATA type to an array. */
Cursor addData(byte[] data);
/**
* Appends an array entry containing a new value of ARRAY type.
* Returns a valid Cursor (that may again be used for adding new
* sub-array entries) referencing the new entry value if
* successful; otherwise returns an invalid Cursor.
*
* @return a new Cursor for the new entry value
*/
Cursor addArray();
/**
* Appends an array entry containing a new value of OBJECT type.
* Returns a valid Cursor (that may again be used for setting
* sub-fields inside the new object) referencing the new entry
* value if successful; otherwise returns an invalid Cursor.
*
* @return a new Cursor for the new entry value
*/
Cursor addObject();
/**
* Sets a field (identified with a symbol id) to contain a new
* value of NIX type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @return new Cursor for the new field value
*/
Cursor setNix(int sym);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param bit the actual boolean value for the new field
* @return new Cursor for the new field value
*/
Cursor setBool(int sym, boolean bit);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param l the actual long value for the new field
* @return new Cursor for the new field value
*/
Cursor setLong(int sym, long l);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param d the actual double value for the new field
* @return new Cursor for the new field value
*/
Cursor setDouble(int sym, double d);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param str the actual string for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(int sym, String str);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param utf8 the actual string (encoded as UTF-8 data) for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(int sym, byte[] utf8);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @param data the actual data to be put into the new field
* @return a new Cursor for the new field value
*/
Cursor setData(int sym, byte[] data);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of ARRAY type. Returns a valid Cursor (that may again be
* used for adding new array entries) referencing the new field
* value if successful; otherwise returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setArray(int sym);
/**
* Sets a field (identified with a symbol id) to contain a new
* value of OBJECT type. Returns a valid Cursor (that may again
* be used for setting sub-fields inside the new object)
* referencing the new field value if successful; otherwise
* returns an invalid Cursor.
*
* @param sym symbol id for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setObject(int sym);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of NIX type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setNix(String name);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of BOOL type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param bit the actual boolean value for the new field
* @return a new Cursor for the new field value
*/
Cursor setBool(String name, boolean bit);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of LONG type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param l the actual long value for the new field
* @return a new Cursor for the new field value
*/
Cursor setLong(String name, long l);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of DOUBLE type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param d the actual double value for the new field
* @return a new Cursor for the new field value
*/
Cursor setDouble(String name, double d);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of STRING type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param str the actual string for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(String name, String str);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of STRING type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param utf8 the actual string (encoded as UTF-8 data) for the new field
* @return a new Cursor for the new field value
*/
Cursor setString(String name, byte[] utf8);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of DATA type. Returns a valid Cursor referencing the new
* field value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @param data the actual data to be put into the new field
* @return a new Cursor for the new field value
*/
Cursor setData(String name, byte[] data);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of ARRAY type. Returns a valid Cursor (that may again be
* used for adding new array entries) referencing the new field
* value if successful; otherwise returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setArray(String name);
/**
* Sets a field (identified with a symbol name) to contain a new
* value of OBJECT type. Returns a valid Cursor (that may again
* be used for setting sub-fields inside the new object)
* referencing the new field value if successful; otherwise
* returns an invalid Cursor.
*
* @param name symbol name for the field to be set
* @return a new Cursor for the new field value
*/
Cursor setObject(String name);
}