Class Value

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.webkitgtk.jsc.Value
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public final class Value extends GObject
JSCValue represents a reference to a value in a JSCContext. The JSCValue protects the referenced value from being garbage collected.

  • Constructor Details

    • Value

      public Value(MemorySegment address)
      Create a Value instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Value

      public Value()
      Create a new Value.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Value class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Value asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GObject
      Returns:
      the instance as if it were its parent type

    • array

      public static Value array(Context context, Type firstItemType, Object... varargs)
      Create a new JSCValue referencing an array with the given items. If firstItemType is G_TYPE_NONE an empty array is created.
      Parameters:
      context - a JSCContext
      firstItemType - GType of first item, or G_TYPE_NONE
      varargs - value of the first item, followed optionally by more type/value pairs, followed by G_TYPE_NONE.
      Returns:
      a JSCValue.

    • arrayBuffer

      public static @Nullable Value arrayBuffer(Context context, @Nullable MemorySegment data, long size)

      Creates a new ArrayBuffer from existing data in memory.

      The data is not copied: while this allows sharing data with JavaScript efficiently, the caller must ensure that the memory region remains valid until the newly created object is released by JSC.

      Optionally, a destroyNotify callback can be provided, which will be invoked with userData as parameter when the ArrayBuffer object is released. This is intended to be used for freeing resources related to the memory region which contains the data:

      GMappedFile *f = g_mapped_file_new (file_path, TRUE, NULL);
JSCValue *value = jsc_value_new_array_buffer (context,
    g_mapped_file_get_contents (f), g_mapped_file_get_length (f),
    (GDestroyNotify) g_mapped_file_unref, f);

      Note that the userData can be the same value as data:

      void *bytes = g_malloc0 (100);
JSCValue *value = jsc_value_new_array_buffer (context, bytes, 100, g_free, bytes);
      Parameters:
      context - A JSCContext
      data - Pointer to a region of memory.
      size - Size in bytes of the memory region.
      Returns:
      A JSCValue, or null in case of exception.
      Since:
      2.38

    • arrayFromGarray

      public static Value arrayFromGarray(Context context, @Nullable Value @Nullable [] array)
      Create a new JSCValue referencing an array with the items from array. If array is null or empty a new empty array will be created. Elements of array should be pointers to a JSCValue.
      Parameters:
      context - a JSCContext
      array - a GPtrArray
      Returns:
      a JSCValue.

    • arrayFromStrv

      public static Value arrayFromStrv(Context context, @Nullable String @Nullable [] strv)
      Create a new JSCValue referencing an array of strings with the items from strv. If array is null or empty a new empty array will be created.
      Parameters:
      context - a JSCContext
      strv - a null-terminated array of strings
      Returns:
      a JSCValue.

    • boolean_

      public static Value boolean_(Context context, boolean value)
      Create a new JSCValue from value
      Parameters:
      context - a JSCContext
      value - a gboolean
      Returns:
      a JSCValue.

    • fromJson

      public static Value fromJson(Context context, String json)
      Create a new JSCValue referencing a new value created by parsing json.
      Parameters:
      context - a JSCContext
      json - the JSON string to be parsed
      Returns:
      a JSCValue.
      Since:
      2.28

    • functionVariadic

      public static Value functionVariadic(Context context, @Nullable String name, @Nullable Callback callback, Type returnType)

      Create a function in context. If name is null an anonymous function will be created. When the function is called by JavaScript or jsc_value_function_call(), callback is called receiving an GPtrArray of JSCValues with the arguments and then userData as last parameter. When the function is cleared in context, destroyNotify is called with userData as parameter.

      Note that the value returned by callback must be fully transferred. In case of boxed types, you could use G_TYPE_POINTER instead of the actual boxed GType to ensure that the instance owned by JSCClass is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a JSCValue created with jsc_value_new_object() that receives the copy as instance parameter.

      Parameters:
      context - a JSCContext
      name - the function name or null
      callback - a GCallback.
      returnType - the GType of the function return value, or G_TYPE_NONE if the function is void.
      Returns:
      a JSCValue.

    • function

      public static Value function(Context context, @Nullable String name, @Nullable Callback callback, Type returnType, @Nullable Type @Nullable [] parameterTypes)

      Create a function in context. If name is null an anonymous function will be created. When the function is called by JavaScript or jsc_value_function_call(), callback is called receiving the function parameters and then userData as last parameter. When the function is cleared in context, destroyNotify is called with userData as parameter.

      Note that the value returned by callback must be fully transferred. In case of boxed types, you could use G_TYPE_POINTER instead of the actual boxed GType to ensure that the instance owned by JSCClass is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a JSCValue created with jsc_value_new_object() that receives the copy as instance parameter.

      Parameters:
      context - a JSCContext
      name - the function name or null
      callback - a GCallback.
      returnType - the GType of the function return value, or G_TYPE_NONE if the function is void.
      parameterTypes - a list of GTypes, one for each parameter, or null
      Returns:
      a JSCValue.

    • null_

      public static Value null_(Context context)
      Create a new JSCValue referencing null in context.
      Parameters:
      context - a JSCContext
      Returns:
      a JSCValue.

    • number

      public static Value number(Context context, double number)
      Create a new JSCValue from number.
      Parameters:
      context - a JSCContext
      number - a number
      Returns:
      a JSCValue.

    • object

      public static Value object(Context context, @Nullable MemorySegment instance, @Nullable Class jscClass)
      Create a new JSCValue from instance. If instance is null a new empty object is created. When instance is provided, jscClass must be provided too. jscClass takes ownership of instance that will be freed by the GDestroyNotify passed to jsc_context_register_class().
      Parameters:
      context - a JSCContext
      instance - an object instance or null
      jscClass - the JSCClass of instance
      Returns:
      a JSCValue.

    • promise

      public static Value promise(Context context, @Nullable Executor executor)
      Creates a new Promise. executor will be invoked during promise initialization and it receives the resolve and reject objects than can be called to resolve or reject the promise. It is called like a JavaScript function, so exceptions raised during the executor invocation will not be propagated to the context, but handled by the promise causing a rejection.
      Parameters:
      context - a JSCContext
      executor - an initialization callback
      Returns:
      a deferred promise object
      Since:
      2.48

    • string

      public static Value string(Context context, @Nullable String string)
      Create a new JSCValue from string. If you need to create a JSCValue from a string containing null characters, use jsc_value_new_string_from_bytes() instead.
      Parameters:
      context - a JSCContext
      string - a null-terminated string
      Returns:
      a JSCValue.

    • stringFromBytes

      public static Value stringFromBytes(Context context, byte @Nullable [] bytes)
      Create a new JSCValue from bytes.
      Parameters:
      context - a JSCContext
      bytes - a GBytes
      Returns:
      a JSCValue.

    • typedArray

      public static Value typedArray(Context context, TypedArrayType type, long length)

      Create a new typed array containing a given amount of elements.

      Create a JSCValue referencing a new typed array with space for length elements of a given type. As all typed arrays must have an associated ArrayBuffer, a new one of suitable size will be allocated to store the elements, which will be initialized to zero.

      The type must not be TypedArrayType.NONE.

      Parameters:
      context - a JSCContext
      type - the type of array elements
      length - number of elements in the array
      Returns:
      a JSCValue
      Since:
      2.38

    • undefined

      public static Value undefined(Context context)
      Create a new JSCValue referencing undefined in context.
      Parameters:
      context - a JSCContext
      Returns:
      a JSCValue.

    • arrayBufferGetData

      public byte[] arrayBufferGetData()

      Gets a pointer to memory that contains the array buffer data.

      Obtains a pointer to the memory region that holds the contents of the ArrayBuffer; modifications done to the data will be visible to JavaScript code. If size is not null, the size in bytes of the memory region will also be stored in the pointed location.

      Note that the pointer returned by this function is not guaranteed to remain the same after calls to other JSC API functions. If you plan to access the data of the ArrayBuffer later, you can keep a reference to the this Value and obtain the data pointer at a later point. Keep in mind that if JavaScript code has a chance to run, for example due to main loop events that result in JSC being called, the contents of the memory region might be modified in the meantime. Consider taking a copy of the data and using the copy instead in asynchronous code.

      Returns:
      pointer to memory.
      Since:
      2.38

    • arrayBufferGetSize

      public long arrayBufferGetSize()

      Gets the size in bytes of the array buffer.

      Obtains the size in bytes of the memory region that holds the contents of an ArrayBuffer.

      Returns:
      size, in bytes.
      Since:
      2.38

    • constructorCall

      public Value constructorCall(@Nullable Value @Nullable [] parameters)
      Invoke new with constructor referenced by value. If nParameters is 0 no parameters will be passed to the constructor.
      Parameters:
      parameters - the JSCValues to pass as parameters to the constructor, or null
      Returns:
      a JSCValue referencing the newly created object instance.

    • functionCall

      public Value functionCall(@Nullable Value @Nullable [] parameters)

      Call function referenced by value, passing the given parameters. If nParameters is 0 no parameters will be passed to the function.

      This function always returns a JSCValue, in case of void functions a JSCValue referencing undefined is returned

      Parameters:
      parameters - the JSCValues to pass as parameters to the function, or null
      Returns:
      a JSCValue with the return value of the function.

    • getContext

      public Context getContext()
      Get the JSCContext in which this Value was created.
      Returns:
      the JSCValue context.

    • isArray

      public boolean isArray()
      Get whether the value referenced by this Value is an array.
      Returns:
      whether the value is an array.

    • isArrayBuffer

      public boolean isArrayBuffer()
      Check whether the this Value is an ArrayBuffer.
      Returns:
      whether the value is an ArrayBuffer
      Since:
      2.38

    • isBoolean

      public boolean isBoolean()
      Get whether the value referenced by this Value is a boolean.
      Returns:
      whether the value is a boolean.

    • isConstructor

      public boolean isConstructor()
      Get whether the value referenced by this Value is a constructor.
      Returns:
      whether the value is a constructor.

    • isFunction

      public boolean isFunction()
      Get whether the value referenced by this Value is a function
      Returns:
      whether the value is a function.

    • isNull

      public boolean isNull()
      Get whether the value referenced by this Value is null.
      Returns:
      whether the value is null.

    • isNumber

      public boolean isNumber()
      Get whether the value referenced by this Value is a number.
      Returns:
      whether the value is a number.

    • isObject

      public boolean isObject()
      Get whether the value referenced by this Value is an object.
      Returns:
      whether the value is an object.

    • isString

      public boolean isString()
      Get whether the value referenced by this Value is a string
      Returns:
      whether the value is a string

    • isTypedArray

      public boolean isTypedArray()
      Determines whether a value is a typed array.
      Returns:
      Whether this Value is a typed array.
      Since:
      2.38

    • isUndefined

      public boolean isUndefined()
      Get whether the value referenced by this Value is undefined.
      Returns:
      whether the value is undefined.

    • newTypedArrayWithBuffer

      public Value newTypedArrayWithBuffer(TypedArrayType type, long offset, long length)

      Create a new typed array value with elements from an array buffer.

      Create a JSCValue referencing a new typed array value containing elements of the given type, where the elements are stored at the memory region represented by the arrayBuffer.

      The type must not be TypedArrayType.NONE.

      The offset and length parameters can be used to indicate which part of the array buffer can be accessed through the typed array. If both are omitted (passing zero as offset, and -1 as length), the whole this Value is exposed through the typed array. Omitting the length with a non-zero offset will expose the remainder of the this Value starting at the indicated offset.

      Parameters:
      type - type of array elements.
      offset - offset, in bytes.
      length - number of array elements, or -1.
      Returns:
      a JSCValue
      Since:
      2.38

    • objectDefinePropertyAccessor

      public void objectDefinePropertyAccessor(String propertyName, Set<ValuePropertyFlags> flags, Type propertyType, @Nullable Callback getter, @Nullable Callback setter)

      Define or modify a property with propertyName in object referenced by value. When the property value is read or set, getter and setter callbacks will be called. When the property is cleared in the JSCClass context, destroyNotify is called with userData as parameter. This is equivalent to JavaScript Object.defineProperty() when used with an accessor descriptor.

      Note that the value returned by getter must be fully transferred. In case of boxed types, you could use G_TYPE_POINTER instead of the actual boxed GType to ensure that the instance owned by JSCClass is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a JSCValue created with jsc_value_new_object() that receives the copy as instance parameter.

      Note that getter and setter are called as functions and not methods, so they don't receive an instance as first parameter. Use jsc_class_add_property() if you want to add property accessor invoked as a method.

      Parameters:
      propertyName - the name of the property to define
      flags - JSCValuePropertyFlags
      propertyType - the GType of the property
      getter - a GCallback to be called to get the property value
      setter - a GCallback to be called to set the property value

    • objectDefinePropertyAccessor

      public void objectDefinePropertyAccessor(String propertyName, ValuePropertyFlags flags, Type propertyType, @Nullable Callback getter, @Nullable Callback setter)

      Define or modify a property with propertyName in object referenced by value. When the property value is read or set, getter and setter callbacks will be called. When the property is cleared in the JSCClass context, destroyNotify is called with userData as parameter. This is equivalent to JavaScript Object.defineProperty() when used with an accessor descriptor.

      Note that the value returned by getter must be fully transferred. In case of boxed types, you could use G_TYPE_POINTER instead of the actual boxed GType to ensure that the instance owned by JSCClass is used. If you really want to return a new copy of the boxed type, use JSC_TYPE_VALUE and return a JSCValue created with jsc_value_new_object() that receives the copy as instance parameter.

      Note that getter and setter are called as functions and not methods, so they don't receive an instance as first parameter. Use jsc_class_add_property() if you want to add property accessor invoked as a method.

      Parameters:
      propertyName - the name of the property to define
      flags - JSCValuePropertyFlags
      propertyType - the GType of the property
      getter - a GCallback to be called to get the property value
      setter - a GCallback to be called to set the property value

    • objectDefinePropertyData

      public void objectDefinePropertyData(String propertyName, Set<ValuePropertyFlags> flags, @Nullable Value propertyValue)
      Define or modify a property with propertyName in object referenced by value. This is equivalent to JavaScript Object.defineProperty() when used with a data descriptor.
      Parameters:
      propertyName - the name of the property to define
      flags - JSCValuePropertyFlags
      propertyValue - the default property value

    • objectDefinePropertyData

      public void objectDefinePropertyData(String propertyName, ValuePropertyFlags flags, @Nullable Value propertyValue)
      Define or modify a property with propertyName in object referenced by value. This is equivalent to JavaScript Object.defineProperty() when used with a data descriptor.
      Parameters:
      propertyName - the name of the property to define
      flags - JSCValuePropertyFlags
      propertyValue - the default property value

    • objectDeleteProperty

      public boolean objectDeleteProperty(String name)
      Try to delete property with name from value. This function will return false if the property was defined without ValuePropertyFlags.CONFIGURABLE flag.
      Parameters:
      name - the property name
      Returns:
      true if the property was deleted, or false otherwise.

    • objectEnumerateProperties

      public @Nullable String @Nullable [] objectEnumerateProperties()
      Get the list of property names of value. Only properties defined with ValuePropertyFlags.ENUMERABLE flag will be collected.
      Returns:
      a null-terminated array of strings containing the property names, or null if this Value doesn't have enumerable properties. Use g_strfreev() to free.

    • objectGetProperty

      public Value objectGetProperty(String name)
      Get property with name from value.
      Parameters:
      name - the property name
      Returns:
      the property JSCValue.

    • objectGetPropertyAtIndex

      public Value objectGetPropertyAtIndex(int index)
      Get property at index from value.
      Parameters:
      index - the property index
      Returns:
      the property JSCValue.

    • objectHasProperty

      public boolean objectHasProperty(String name)
      Get whether this Value has property with name.
      Parameters:
      name - the property name
      Returns:
      true if this Value has a property with name, or false otherwise

    • objectInvokeMethod

      public Value objectInvokeMethod(String name, @Nullable Value @Nullable [] parameters)

      Invoke method with name on object referenced by value, passing the given parameters. If nParameters is 0 no parameters will be passed to the method. The object instance will be handled automatically even when the method is a custom one registered with jsc_class_add_method(), so it should never be passed explicitly as parameter of this function.

      This function always returns a JSCValue, in case of void methods a JSCValue referencing undefined is returned.

      Parameters:
      name - the method name
      parameters - the JSCValues to pass as parameters to the method, or null
      Returns:
      a JSCValue with the return value of the method.

    • objectIsInstanceOf

      public boolean objectIsInstanceOf(String name)
      Get whether the value referenced by this Value is an instance of class name.
      Parameters:
      name - a class name
      Returns:
      whether the value is an object instance of class name.

    • objectSetProperty

      public void objectSetProperty(String name, Value property)
      Set property with name on value.
      Parameters:
      name - the property name
      property - the JSCValue to set

    • objectSetPropertyAtIndex

      public void objectSetPropertyAtIndex(int index, Value property)
      Set property at index on value.
      Parameters:
      index - the property index
      property - the JSCValue to set

    • toBoolean

      public boolean toBoolean()
      Convert this Value to a boolean.
      Returns:
      a gboolean result of the conversion.

    • toDouble

      public double toDouble()
      Convert this Value to a double.
      Returns:
      a gdouble result of the conversion.

    • toInt32

      public int toInt32()
      Convert this Value to a gint32.
      Returns:
      a gint32 result of the conversion.

    • toJson

      public String toJson(int indent)
      Create a JSON string of this Value serialization. If indent is 0, the resulting JSON will not contain newlines. The size of the indent is clamped to 10 spaces.
      Parameters:
      indent - The number of spaces to indent when nesting.
      Returns:
      a null-terminated JSON string with serialization of this Value
      Since:
      2.28

    • toString

      public String toString()
      Convert this Value to a string. Use jsc_value_to_string_as_bytes() instead, if you need to handle strings containing null characters.
      Overrides:
      toString in class Object
      Returns:
      a null-terminated string result of the conversion.

    • toStringAsBytes

      public byte[] toStringAsBytes()
      Convert this Value to a string and return the results as GBytes. This is needed to handle strings with null characters.
      Returns:
      a GBytes with the result of the conversion.

    • typedArrayGetBuffer

      public Value typedArrayGetBuffer()
      Obtain the ArrayBuffer for the memory region of the typed array elements.
      Returns:
      A JSCValue
      Since:
      2.38

    • typedArrayGetData

      public @Nullable MemorySegment typedArrayGetData(@Nullable Out<Long> length)

      Obtains a pointer to the memory region that holds the elements of the typed array; modifications done to them will be visible to JavaScript code. If length is not null, the number of elements contained in the typed array are also stored in the pointed location.

      The returned pointer needs to be casted to the appropriate type (see JSCTypedArrayType), and has the offset over the underlying array buffer data applied—that is, points to the first element of the typed array:

      if (jsc_value_typed_array_get_type(value) != JSC_TYPED_ARRAY_UINT32)
    g_error ("Only arrays of uint32_t are supported");

gsize count = 0;
uint32_t *elements = jsc_value_typed_array_get_contents (value, &count);
for (gsize i = 0; i < count; i++)
     g_print ("index %zu, value %" PRIu32 "\\n", i, elements[i]);

      Note that the pointer returned by this function is not guaranteed to remain the same after calls to other JSC API functions. See jsc_value_array_buffer_get_data() for details.

      Parameters:
      length - location to return the number of elements contained
      Returns:
      pointer to memory.
      Since:
      2.38

    • typedArrayGetLength

      public long typedArrayGetLength()
      Gets the number of elements in a typed array.
      Returns:
      number of elements.
      Since:
      2.38

    • typedArrayGetOffset

      public long typedArrayGetOffset()
      Gets the offset over the underlying array buffer data.
      Returns:
      offset, in bytes.
      Since:
      2.38

    • typedArrayGetSize

      public long typedArrayGetSize()
      Gets the size of a typed array.
      Returns:
      size, in bytes.
      Since:
      2.38

    • typedArrayGetType

      public TypedArrayType typedArrayGetType()
      Gets the type of elements contained in a typed array.
      Returns:
      type of the elements, or TypedArrayType.NONE if this Value is not a typed array.
      Since:
      2.38

    • builder

      public static Value.Builder<? extends Value.Builder> builder()
      A Value.Builder object constructs a Value with the specified properties. Use the various set...() methods to set properties, and finish construction with Value.Builder.build().
      Returns:
      the builder object