Class DebugValue

java.lang.Object

com.oracle.truffle.api.debug.DebugValue

public abstract class DebugValue
extends Object

Represents a value accessed using the debugger API. Please note that values can become invalid depending on the context in which they are used. For example stack values will only remain valid as long as the current stack element is active. Heap values on the other hand remain valid. If a value becomes invalid then setting or getting a value will throw an IllegalStateException . DebugValue instances neither support equality or preserve identity.

Clients may access the debug value only on the execution thread where the suspended event of the stack frame was created and notification received; access from other threads will throw IllegalStateException.

Since:

0.17

Method Summary

Modifier and Type	Method	Description
abstract <T> T	as(Class<T> clazz)	Deprecated. Use toDisplayString() instead.
BigInteger	asBigInteger()	Returns a BigInteger representation of this value if it is number and the value fits.
boolean	asBoolean()	Returns a boolean representation of this value if it is boolean.
byte	asByte()	Returns a byte representation of this value if it is number and the value fits.
LocalDate	asDate()	Returns this value as date if it is a date.
double	asDouble()	Returns a double representation of this value if it is number and the value fits.
Duration	asDuration()	Returns this value as duration if this object represents a duration.
float	asFloat()	Returns a float representation of this value if it is number and the value fits.
final DebugValue	asInLanguage(LanguageInfo language)	Returns a debug value that presents itself as seen by the provided language.
Instant	asInstant()	Returns this value as instant if it is an instant.
int	asInt()	Returns an int representation of this value if it is number and the value fits.
long	asLong()	Returns a long representation of this value if it is number and the value fits.
short	asShort()	Returns a short representation of this value if it is number and the value fits.
final String	asString()	Returns the String value if this value represents a string.
LocalTime	asTime()	Returns this value as time if it is a time.
ZoneId	asTimeZone()	Returns this value as timestamp if it represents a timezone.
final boolean	canExecute()	Returns true if this value can be executed (represents a guest language function), else false.
boolean	equals(Object obj)	Indicates whether another DebugValue is equal to this.
final DebugValue	execute(DebugValue... arguments)	Executes the executable represented by this value.
boolean	fitsInBigInteger()	Returns true if this value represents a number and the value fits in BigInteger, else false.
boolean	fitsInByte()	Returns true if this value represents a number and the value fits in byte, else false.
boolean	fitsInDouble()	Returns true if this value represents a number and the value fits in double, else false.
boolean	fitsInFloat()	Returns true if this value represents a number and the value fits in float, else false.
boolean	fitsInInt()	Returns true if this value represents a number and the value fits in int, else false.
boolean	fitsInLong()	Returns true if this value represents a number and the value fits in long, else false.
boolean	fitsInShort()	Returns true if this value represents a number and the value fits in short, else false.
List<DebugValue>	getArray()	Provides array elements when this value represents an array.
DebugValue	getHashEntriesIterator()	Returns the entries iterator of the hash map.
DebugValue	getHashKeysIterator()	Returns the keys iterator of the hash map.
long	getHashSize()	Returns the number of hash map entries.
DebugValue	getHashValue(DebugValue key)	Get value of a hash map for the specified key or null if the mapping for the specified key does not exist.
DebugValue	getHashValueOrDefault(DebugValue key, DebugValue defaultValue)	Get value of a hash map for the specified key or return the defaultValue when the mapping for the specified key does not exist or is not readable.
DebugValue	getHashValuesIterator()	Returns the values iterator of the hash map.
DebugValue	getIterator()	Returns the iterator value.
DebugValue	getIteratorNextElement()	Returns the next element in the iteration.
final DebugValue	getMetaObject()	Get a meta-object of this value, if any.
String	getMetaQualifiedName()	Returns the qualified name of a metaobject as String.
String	getMetaSimpleName()	Returns the simple name of a metaobject as string.
abstract String	getName()	Returns the name of this value as it is referred to from its origin.
final LanguageInfo	getOriginalLanguage()	Get the original language that created the value, if any.
final Collection<DebugValue>	getProperties()	Provides properties representing an internal structure of this value.
final DebugValue	getProperty(String name)	Get a property value by its name.
Object	getRawValue(Class<? extends TruffleLanguage<?>> languageClass)	Returns the underlying guest value object held by this DebugValue.
final List<Breakpoint>	getRootInstanceBreakpoints()	Get a list of breakpoints installed to the value's session and whose root instance is this value.
DebugScope	getScope()	Get the scope where this value is declared in.
abstract DebuggerSession	getSession()	Get the debugger session associated with this value.
final SourceSection	getSourceLocation()	Get a source location where this value is declared, if any.
boolean	hasHashEntries()	Returns true if the value may have hash map entries.
int	hashCode()	Provides hash code of the value.
boolean	hasIterator()	Returns true if the value provides an iterator.
boolean	hasIteratorNextElement()	Returns true if the value is an iterator which has more elements, else false.
abstract boolean	hasReadSideEffects()	Returns true if reading of this value can have side-effects, else false.
abstract boolean	hasWriteSideEffects()	Returns true if setting a new value can have side-effects, else false.
final boolean	isArray()	Returns true if this value represents an array, false otherwise.
boolean	isBoolean()	Returns true if and only if this value represents a boolean value.
boolean	isDate()	Returns true if this value represents a date, else false.
boolean	isDuration()	Returns true if this object represents a duration, else false.
boolean	isHashEntryExisting(DebugValue key)	Returns true if mapping for a given key is existing.
boolean	isHashEntryInsertable(DebugValue key)	Returns true if mapping for the specified key does not exist and is writable.
boolean	isHashEntryModifiable(DebugValue key)	Returns true if mapping for the specified key exists and is writable.
boolean	isHashEntryReadable(DebugValue key)	Returns true if mapping for the specified key exists and is readable.
boolean	isHashEntryRemovable(DebugValue key)	Returns true if mapping for the specified key exists and is removable.
boolean	isHashEntryWritable(DebugValue key)	Returns true if mapping for the specified key is modifiable or insertable.
boolean	isInstant()	Returns true if this value represents an instant.
abstract boolean	isInternal()	Returns true if this value represents an internal variable or property, false otherwise.
boolean	isIterator()	Returns true if this value represents an iterator.
boolean	isMetaInstance(DebugValue instance)	Returns true if the given instance is an instance of this value, else false.
boolean	isMetaObject()	Returns true if the value represents a metaobject.
final boolean	isNull()	Test if the value represents 'null'.
boolean	isNumber()	Returns true if and only if this value represents a number.
abstract boolean	isReadable()	Returns true if this value can be read else false.
boolean	isString()	Returns true if and only if this value represents a string.
boolean	isTime()	Returns true if this value represents a time, else false.
boolean	isTimeZone()	Returns true if this object represents a timezone, else false.
abstract boolean	isWritable()	Returns true if this value can be written to, else false.
void	putHashEntry(DebugValue key, DebugValue value)	Associates the specified value with the specified key in the hash map.
boolean	removeHashEntry(DebugValue key)	Removes the mapping for a given key from the hash map.
abstract void	set(DebugValue value)	Sets the value using another DebugValue.
abstract void	set(Object primitiveValue)	Deprecated. in 21.2.
final String	toDisplayString()	Converts the value to a language-specific string representation.
final String	toDisplayString(boolean allowSideEffects)	Converts the value to a language-specific string representation.
String	toString()	Returns a string representation of the debug value.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

set

public abstract void set(DebugValue value)
                  throws DebugException

Sets the value using another DebugValue. Throws an IllegalStateException if the value is not writable, the passed value is not readable, this value or the passed value is invalid, or the guest language of the values do not match. Use DebugStackFrame.eval(String) to evaluate values to be set.

Parameters:

value - the value to set

Throws:

DebugException - when guest language code throws an exception

Since:

0.17

set

@Deprecated(since="21.2")
public abstract void set(Object primitiveValue)
                  throws DebugException

Deprecated.

in 21.2. Use set(getSession().createPrimitiveValue(primitiveValue, null)) instead.

Sets a primitive value. Strings and boxed Java primitive types are considered primitive. Throws an IllegalStateException if the value is not writable and IllegalArgumentException if the value is not primitive.

Parameters:

primitiveValue - a primitive value to set

Throws:

DebugException - when guest language code throws an exception

Since:

19.0

as

@Deprecated(since="20.1")
public abstract <T> T as(Class<T> clazz)
                  throws DebugException

Deprecated.

Use toDisplayString() instead.

Converts the debug value into a Java type. Class conversions which are always supported:

• String.class converts the value to its language specific string representation.
• Number.class converts the value to a Number representation, if any.
• Boolean.class converts the value to a Boolean representation, if any.

No optional conversions are currently available. If a conversion is not supported then an UnsupportedOperationException is thrown. If the value is not readable then an IllegalStateException is thrown.

Parameters:

clazz - the type to convert to

Returns:

the converted Java type, or null when the conversion was not possible.

Throws:

DebugException - when guest language code throws an exception

Since:

0.17

getName

public abstract String getName()

Returns the name of this value as it is referred to from its origin. If this value is originated from the stack it returns the name of the local variable. If the value was returned from another objects then it returns the name of the property or field it is contained in. If no name is available null is returned.

Since:

0.17

isReadable

public abstract boolean isReadable()

Returns true if this value can be read else false.

Since:

0.17

hasReadSideEffects

public abstract boolean hasReadSideEffects()

Returns true if reading of this value can have side-effects, else false. Read has side-effects if it changes runtime state.

Since:

19.0

hasWriteSideEffects

public abstract boolean hasWriteSideEffects()

Returns true if setting a new value can have side-effects, else false. Write has side-effects if it changes runtime state besides this value.

Since:

19.0

isWritable

public abstract boolean isWritable()

Returns true if this value can be written to, else false.

Since:

0.26

isInternal

public abstract boolean isInternal()

Returns true if this value represents an internal variable or property, false otherwise.

Languages might have extra object properties or extra scope variables that are a part of the runtime, but do not correspond to anything what is an explicit part of the guest language representation. They may represent additional language artifacts, providing more in-depth information that can be valuable during debugging. Language implementors mark these variables as internal. An example of such internal values are internal slots in ECMAScript.

Since:

0.26

getScope

public DebugScope getScope()

Get the scope where this value is declared in. It returns a non-null value for local variables declared on a stack. It's null for object properties and other heap values.

Returns:

the scope, or null when this value does not belong into any scope.

Since:

0.26

isNull

public final boolean isNull()

Test if the value represents 'null'.

Throws:

DebugException - when guest language code throws an exception

Since:

19.0

isString

public boolean isString()

Returns true if and only if this value represents a string.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

asString

public final String asString()
                      throws DebugException

Returns the String value if this value represents a string. This method returns null otherwise.

Throws:

DebugException - when guest language code throws an exception

Since:

19.0

fitsInInt

public boolean fitsInInt()

Returns true if this value represents a number and the value fits in int, else false.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asInt()

asInt

public int asInt()

Returns an int representation of this value if it is number and the value fits.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• fitsInInt()

isBoolean

public boolean isBoolean()

Returns true if and only if this value represents a boolean value.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asBoolean()

asBoolean

public boolean asBoolean()

Returns a boolean representation of this value if it is boolean.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isBoolean()

isNumber

public boolean isNumber()

Returns true if and only if this value represents a number. The number value may be accessed as byte, short, int, long, float or double value.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

fitsInLong

public boolean fitsInLong()

Returns true if this value represents a number and the value fits in long, else false.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asLong()

asLong

public long asLong()

Returns a long representation of this value if it is number and the value fits.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• fitsInLong()

fitsInBigInteger

public boolean fitsInBigInteger()

Returns true if this value represents a number and the value fits in BigInteger, else false.

Throws:

DebugException - when guest language code throws an exception

Since:

23.0.0

See Also:

• asBigInteger()

asBigInteger

public BigInteger asBigInteger()

Returns a BigInteger representation of this value if it is number and the value fits.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

23.0.0

See Also:

• fitsInBigInteger()

fitsInDouble

public boolean fitsInDouble()

Returns true if this value represents a number and the value fits in double, else false.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asDouble()

asDouble

public double asDouble()

Returns a double representation of this value if it is number and the value fits.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• fitsInDouble()

fitsInFloat

public boolean fitsInFloat()

Returns true if this value represents a number and the value fits in float, else false.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asFloat()

asFloat

public float asFloat()

Returns a float representation of this value if it is number and the value fits.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• fitsInFloat()

fitsInByte

public boolean fitsInByte()

Returns true if this value represents a number and the value fits in byte, else false.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asByte()

asByte

public byte asByte()

Returns a byte representation of this value if it is number and the value fits.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• fitsInByte()

fitsInShort

public boolean fitsInShort()

Returns true if this value represents a number and the value fits in short, else false.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asShort()

asShort

public short asShort()

Returns a short representation of this value if it is number and the value fits.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• fitsInShort()

isDate

public boolean isDate()

Returns true if this value represents a date, else false. If this value is also a timezone then the date is aware, otherwise it is naive.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asDate()

asDate

public LocalDate asDate()

Returns this value as date if it is a date. The returned date is either aware if the value has a timezone otherwise it is naive.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isDate()

isTime

public boolean isTime()

Returns true if this value represents a time, else false. If the value is also a timezone then the time is aware, otherwise it is naive.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asTime()

asTime

public LocalTime asTime()

Returns this value as time if it is a time. The returned time is either aware if the value has a timezone otherwise it is naive.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isTime()

isInstant

public boolean isInstant()

Returns true if this value represents an instant. See InteropLibrary.isInstant(Object) for detailed description.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isDate()
• isTime()
• isInstant()
• asInstant()

asInstant

public Instant asInstant()

Returns this value as instant if it is an instant. See InteropLibrary.asInstant(Object) for detailed description.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isDate()
• isTime()
• isTimeZone()

isTimeZone

public boolean isTimeZone()

Returns true if this object represents a timezone, else false. See InteropLibrary.isTimeZone(Object) for detailed description.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• asTimeZone()
• asInstant()

asTimeZone

public ZoneId asTimeZone()

Returns this value as timestamp if it represents a timezone.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isTimeZone()

isDuration

public boolean isDuration()

Returns true if this object represents a duration, else false.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• Duration
• asDuration()

asDuration

public Duration asDuration()

Returns this value as duration if this object represents a duration.

Throws:

UnsupportedOperationException - if this value could not be converted.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isDuration()

isMetaObject

public boolean isMetaObject()

Returns true if the value represents a metaobject. See InteropLibrary.isMetaObject(Object) for detailed description.

Throws:

DebugException - when guest language code throws an exception

Since:

20.1

See Also:

• getMetaQualifiedName()
• getMetaSimpleName()
• isMetaInstance(DebugValue)
• getMetaObject()

getMetaQualifiedName

public String getMetaQualifiedName()

Returns the qualified name of a metaobject as String. See InteropLibrary.getMetaQualifiedName(Object) for detailed description.

Throws:

UnsupportedOperationException - if and only if isMetaObject() returns false for the same value.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isMetaObject()

getMetaSimpleName

public String getMetaSimpleName()

Returns the simple name of a metaobject as string. See InteropLibrary.getMetaSimpleName(Object) for detailed description.

Throws:

UnsupportedOperationException - if and only if isMetaObject() returns false for the same value.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isMetaObject()

isMetaInstance

public boolean isMetaInstance(DebugValue instance)

Returns true if the given instance is an instance of this value, else false. See InteropLibrary.isMetaInstance(Object, Object) for detailed description.

Parameters:

instance - the instance value to check.

Throws:

UnsupportedOperationException - if and only if isMetaObject() returns false for the same value.

DebugException - when guest language code throws an exception

Since:

20.1.0

See Also:

• isMetaObject()

getRootInstanceBreakpoints

public final List<Breakpoint> getRootInstanceBreakpoints()

Get a list of breakpoints installed to the value's session and whose root instance is this value.

Returns:

a list of breakpoints with this value as root instance

Since:

19.3.0

getProperties

public final Collection<DebugValue> getProperties()
                                           throws DebugException

Provides properties representing an internal structure of this value. The returned collection is not thread-safe. If the value is not readable then null is returned.

Returns:

a collection of property values, or null when the value does not have any concept of properties.

Throws:

DebugException - when guest language code throws an exception

Since:

0.19

getProperty

public final DebugValue getProperty(String name)
                             throws DebugException

Get a property value by its name.

Parameters:

name - name of a property

Returns:

the property value, or null if the property does not exist.

Throws:

DebugException - when guest language code throws an exception

Since:

19.0

isArray

public final boolean isArray()
                      throws DebugException

Returns true if this value represents an array, false otherwise.

Throws:

DebugException - when guest language code throws an exception

Since:

0.19

getArray

public List<DebugValue> getArray()
                          throws DebugException

Provides array elements when this value represents an array. To test if this value represents an array, check isArray().

Returns:

a list of array elements, or null when the value does not represent an array.

Throws:

DebugException - when guest language code throws an exception

Since:

0.19

getRawValue

public Object getRawValue(Class<? extends TruffleLanguage<?>> languageClass)

Returns the underlying guest value object held by this DebugValue. This method is permitted only if the guest language class is available. This is the case if you want to utilize the Debugger API directly from within a guest language, or if you are an instrument bound/dependent on a specific language. This method is opposite to DebugScope.convertRawValue(Class, Object) where a raw guest language value is wrapped in a DebugValue.

Parameters:

languageClass - the Truffle language class for a given guest language

Returns:

the guest language object or null if the language differs from the language that created the underlying DebugValue

Since:

20.1

toDisplayString

public final String toDisplayString()

Converts the value to a language-specific string representation. Is the same as toDisplayString(true).

Since:

20.1

See Also:

• toDisplayString(boolean)

toDisplayString

public final String toDisplayString(boolean allowSideEffects)
                             throws DebugException

Converts the value to a language-specific string representation.

Parameters:

allowSideEffects - whether side-effects are allowed in the production of the string.

Throws:

DebugException

Since:

20.1

getMetaObject

public final DebugValue getMetaObject()
                               throws DebugException

Get a meta-object of this value, if any. The meta-object represents a description of the value, reveals it's kind and it's features. See InteropLibrary.getMetaObject(Object) for detailed description.

Returns:

a value representing the meta-object, or null

Throws:

DebugException - when guest language code throws an exception

Since:

0.22

getSourceLocation

public final SourceSection getSourceLocation()
                                      throws DebugException

Get a source location where this value is declared, if any.

Returns:

a source location of the object, or null

Throws:

DebugException - when guest language code throws an exception

Since:

0.22

canExecute

public final boolean canExecute()
                         throws DebugException

Returns true if this value can be executed (represents a guest language function), else false.

Throws:

DebugException

Since:

19.0

execute

public final DebugValue execute(DebugValue... arguments)
                         throws DebugException

Executes the executable represented by this value.

Parameters:

arguments - Arguments passed to the executable

Returns:

the result of the execution

Throws:

DebugException - when guest language code throws an exception

Since:

19.0

See Also:

• canExecute()

hasIterator

public boolean hasIterator()
                    throws DebugException

Returns true if the value provides an iterator. For details see InteropLibrary.hasIterator(Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

See Also:

• getIterator()

getIterator

public DebugValue getIterator()
                       throws DebugException

Returns the iterator value. The return value is always an iterator. For details see InteropLibrary.getIterator(Object).

Throws:

DebugException - if hasIterator() returns false or guest language code throws an exception.

Since:

21.3

See Also:

• hasIterator()

isIterator

public boolean isIterator()
                   throws DebugException

Returns true if this value represents an iterator. For details see InteropLibrary.isIterator(Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

See Also:

• hasIterator()
• getIterator()

hasIteratorNextElement

public boolean hasIteratorNextElement()
                               throws DebugException

Returns true if the value is an iterator which has more elements, else false. For details see InteropLibrary.hasIteratorNextElement(Object).

Throws:

DebugException - if isIterator() returns false or guest language code throws an exception.

Since:

21.2

See Also:

• isIterator()
• getIteratorNextElement()

getIteratorNextElement

public DebugValue getIteratorNextElement()
                                  throws NoSuchElementException,
DebugException

Returns the next element in the iteration. When the underlying data structure is modified the getIteratorNextElement() may throw the NoSuchElementException despite the hasIteratorNextElement() returned true.

Throws:

DebugException - if isIterator() returns false or when the underlying iterator element exists but is not readable, or guest language code throws an exception.

NoSuchElementException - if the iteration has no more elements.

Since:

21.2

See Also:

• isIterator()
• hasIteratorNextElement()
• InteropLibrary.getIteratorNextElement(Object)

hasHashEntries

public boolean hasHashEntries()
                       throws DebugException

Returns true if the value may have hash map entries. For details see InteropLibrary.hasHashEntries(Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

See Also:

• getHashEntriesIterator()
• getHashSize()
• isHashEntryReadable(DebugValue)
• isHashEntryWritable(DebugValue)
• isHashEntryInsertable(DebugValue)
• isHashEntryRemovable(DebugValue)
• getHashValue(DebugValue)
• getHashValueOrDefault(DebugValue, DebugValue)
• putHashEntry(DebugValue, DebugValue)
• removeHashEntry(DebugValue)

getHashSize

public long getHashSize()
                 throws DebugException

Returns the number of hash map entries.

Throws:

DebugException - if hasHashEntries() returns false or guest language code throws an exception.

Since:

21.2

See Also:

• hasHashEntries()

isHashEntryReadable

public boolean isHashEntryReadable(DebugValue key)
                            throws DebugException

Returns true if mapping for the specified key exists and is readable. If the key is obtained from getHashEntriesIterator() or getHashKeysIterator(), it returns the same value as key.isReadable(). For details see InteropLibrary.isHashEntryReadable(Object, Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

See Also:

• getHashValue(DebugValue)

getHashValue

public DebugValue getHashValue(DebugValue key)
                        throws DebugException

Get value of a hash map for the specified key or null if the mapping for the specified key does not exist. The returned value, if any, is writable if and only if isHashEntryWritable(DebugValue) returns true for the entry key.

Throws:

DebugException - if the value has no hash entries, or guest language code throws an exception.

Since:

21.2

See Also:

• isHashEntryReadable(DebugValue)
• getHashValueOrDefault(DebugValue, DebugValue)

getHashValueOrDefault

public DebugValue getHashValueOrDefault(DebugValue key,
 DebugValue defaultValue)
                                 throws DebugException

Get value of a hash map for the specified key or return the defaultValue when the mapping for the specified key does not exist or is not readable.

Throws:

DebugException - if the hash map does not support reading at all, or guest language code throws an exception.

Since:

21.2

See Also:

• isHashEntryReadable(DebugValue)
• getHashValue(DebugValue)

isHashEntryModifiable

public boolean isHashEntryModifiable(DebugValue key)
                              throws DebugException

Returns true if mapping for the specified key exists and is writable. If the corresponding value is obtained from getHashValue(DebugValue) or from getHashEntriesIterator(), then it returns the same value as value.isWritable(). For details see InteropLibrary.isHashEntryModifiable(Object, Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

See Also:

• putHashEntry(DebugValue, DebugValue)

isHashEntryInsertable

public boolean isHashEntryInsertable(DebugValue key)
                              throws DebugException

Returns true if mapping for the specified key does not exist and is writable. For details see InteropLibrary.isHashEntryInsertable(Object, Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

See Also:

• putHashEntry(DebugValue, DebugValue)

isHashEntryWritable

public boolean isHashEntryWritable(DebugValue key)
                            throws DebugException

Returns true if mapping for the specified key is modifiable or insertable.

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

putHashEntry

public void putHashEntry(DebugValue key,
 DebugValue value)
                  throws DebugException

Associates the specified value with the specified key in the hash map. Putting the entry is allowed if is existing and modifiable, or not existing and insertable.

Throws:

DebugException - if the hash map does not support writing at all, or mapping for the specified key is not modifiable nor insertable, or the provided key type or value type is not allowed to be written, or guest language code throws an exception.

Since:

21.2

isHashEntryRemovable

public boolean isHashEntryRemovable(DebugValue key)
                             throws DebugException

Returns true if mapping for the specified key exists and is removable. For details see InteropLibrary.isHashEntryRemovable(Object, Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

See Also:

• removeHashEntry(DebugValue)

removeHashEntry

public boolean removeHashEntry(DebugValue key)
                        throws DebugException

Removes the mapping for a given key from the hash map. Mapping removing is allowed if it is removable.

Returns:

true if the mapping was successfully removed, false if mapping for a given key does not exist.

Throws:

DebugException - if the value does not have any hash entries or if mapping for specified key exists but cannot be removed.

Since:

21.2

See Also:

• isHashEntryRemovable(DebugValue)

isHashEntryExisting

public boolean isHashEntryExisting(DebugValue key)
                            throws DebugException

Returns true if mapping for a given key is existing. For details see InteropLibrary.isHashEntryExisting(Object, Object).

Throws:

DebugException - if guest language code throws an exception.

Since:

21.2

getHashEntriesIterator

public DebugValue getHashEntriesIterator()
                                  throws DebugException

Returns the entries iterator of the hash map. The return value is always an iterator of array elements. The first array element is a key, the second array element is the associated value. Array elements returned by the iterator may be modifiable. Set of the elements updates the hash map.

Throws:

DebugException - if hasHashEntries() returns false, or if guest language code throws an exception.

Since:

21.2

getHashKeysIterator

public DebugValue getHashKeysIterator()
                               throws DebugException

Returns the keys iterator of the hash map. The return value is always an iterator.

Throws:

DebugException - if hasHashEntries() returns false, or if guest language code throws an exception.

Since:

21.2

getHashValuesIterator

public DebugValue getHashValuesIterator()
                                 throws DebugException

Returns the values iterator of the hash map. The return value is always an iterator.

Throws:

DebugException - if hasHashEntries() returns false, or if guest language code throws an exception.

Since:

21.2

hashCode

public int hashCode()
             throws DebugException

Provides hash code of the value.

Overrides:

hashCode in class Object

Returns:

identity hash code of the guest object, if the object has identity.

Throws:

DebugException - when guest language code throws an exception

Since:

21.2

equals

public boolean equals(Object obj)
               throws DebugException

Indicates whether another DebugValue is equal to this. Two DebugValue objects are equal if and only if their guest objects are identical.

Overrides:

equals in class Object

Throws:

DebugException - when guest language code throws an exception

Since:

21.2

getOriginalLanguage

public final LanguageInfo getOriginalLanguage()
                                       throws DebugException

Get the original language that created the value, if any. This method will return null for values representing a primitive value, or objects that are not associated with any language.

Returns:

the language, or null when no language can be identified as the creator of the value.

Throws:

DebugException - when guest language code throws an exception

Since:

0.27

asInLanguage

public final DebugValue asInLanguage(LanguageInfo language)

Returns a debug value that presents itself as seen by the provided language. The language affects the output of toDisplayString(), getMetaObject(), getSourceLocation() and other methods that provide various representations of the value. The original language of the returned value remains the same as of this value.

Parameters:

language - a language to get the value representation of

Returns:

the value as represented in the language

Since:

0.27

getSession

public abstract DebuggerSession getSession()

Get the debugger session associated with this value.

Since:

21.2

toString

public String toString()

Returns a string representation of the debug value.

Overrides:

toString in class Object

Since:

0.17