Interface ValueCoercible

All Superinterfaces:
Boxed<org.graalvm.polyglot.Value>, org.graalvm.polyglot.proxy.Proxy, org.graalvm.polyglot.proxy.ProxyObject
All Known Subinterfaces:
PooledValueCoercible
public interface ValueCoercible extends Boxed<org.graalvm.polyglot.Value>, org.graalvm.polyglot.proxy.ProxyObject
Generated Java wrapper for a Python object that can expose its underlying polyglot value.

Micronaut Python bridge classes implement this interface so Java code can keep a strongly typed wrapper while GraalPy can still interact with the original Python object through ProxyObject. The interface also defines Micronaut-specific proxy members used to recover the generated host wrapper and to bridge generated JavaBean-style accessors back to Python attributes.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    ValueCoercible.GeneratedPropertyMembers
    Build-time generated JavaBean accessor aliases for Python wrappers.
    static final record 
    ValueCoercible.HostObjectReference
    Private host reference exposed through HOST_OBJECT_MEMBER.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    AS_POLYGLOT_VALUE_MEMBER
     
    static final String
    HOST_OBJECT_MEMBER
     

  • Method Summary

    Modifier and Type
    Method
    Description
    default org.graalvm.polyglot.Value
    $unbox()
    Unboxes this wrapper for Micronaut conversion infrastructure.
    @NonNull org.graalvm.polyglot.Value
    asPolyglotValue()
    Returns the wrapped Python value.
    default @Nullable Object
    getMember(String key)
    Exposes the wrapped Python value as a polyglot proxy member.
    default Object
    getMemberKeys()
    Returns member keys exposed by the wrapped Python object.
    default boolean
    hasMember(String key)
    Tests whether a member is available through this proxy.
    static @Nullable ValueCoercible
    hostObject(@Nullable org.graalvm.polyglot.Value value)
    Extracts a generated Java wrapper from a polyglot value when one is available.
    static @Nullable Object
    hostObject(@Nullable org.graalvm.polyglot.Value value, Class<?> targetType)
    Extracts a host object of the requested type from a polyglot value.
    static @Nullable ValueCoercible
    hostObject(@Nullable org.graalvm.polyglot.proxy.ProxyObject value)
    Extracts a generated Java wrapper from a proxy object when one is available.
    static @Nullable Object
    hostObject(@Nullable org.graalvm.polyglot.proxy.ProxyObject value, Class<?> targetType)
    Extracts a host object of the requested type from a proxy object.
    static boolean
    matchesArgument(org.graalvm.polyglot.Value value, Class<?> targetType)
    Match one Python argument against a Java parameter type without conversion.
    default void
    putMember(String key, org.graalvm.polyglot.Value value)
    Writes a member to the wrapped Python object.

    Methods inherited from interface org.graalvm.polyglot.proxy.ProxyObject

    removeMember

  • Field Details

  • Method Details

    • asPolyglotValue

      @NonNull @NonNull org.graalvm.polyglot.Value asPolyglotValue()
      Returns the wrapped Python value.

      The returned value belongs to the runtime context that created this wrapper, except for pooled wrappers where PooledValueCoercible.asPolyglotValue(org.graalvm.polyglot.Context) can resolve an equivalent value for a specific event-loop context.

      Returns:
      The wrapped Python polyglot value.

    • $unbox

      default org.graalvm.polyglot.Value $unbox()
      Unboxes this wrapper for Micronaut conversion infrastructure.
      Specified by:
      $unbox in interface Boxed<org.graalvm.polyglot.Value>
      Returns:
      The wrapped Python polyglot value.

    • getMember

      default @Nullable Object getMember(String key)
      Exposes the wrapped Python value as a polyglot proxy member.

      Generated Python bridge classes implement ProxyObject through this interface so GraalPy can read members from the underlying Python object. Two Micronaut-specific members are handled before delegating to Python: HOST_OBJECT_MEMBER exposes a private host reference used to recover the generated Java wrapper, and AS_POLYGLOT_VALUE_MEMBER exposes a zero-argument callable that returns the wrapped Value. JavaBean-style generated accessor aliases are resolved after direct Python members.

      Specified by:
      getMember in interface org.graalvm.polyglot.proxy.ProxyObject
      Parameters:
      key - The requested member name.
      Returns:
      The member value, a generated accessor callable, or null when the Python member is None or no member is available.

    • getMemberKeys

      default Object getMemberKeys()
      Returns member keys exposed by the wrapped Python object.

      Micronaut-specific synthetic members are intentionally omitted from the returned key set so Python-side enumeration reflects the user object's members.

      Specified by:
      getMemberKeys in interface org.graalvm.polyglot.proxy.ProxyObject
      Returns:
      The wrapped Python member names as a String[], or an empty array when the wrapped value has no members.

    • hasMember

      default boolean hasMember(String key)
      Tests whether a member is available through this proxy.

      The check includes Micronaut's synthetic bridge members, direct members of the wrapped Python object, and generated JavaBean accessor aliases for bridge classes that implement ValueCoercible.GeneratedPropertyMembers.

      Specified by:
      hasMember in interface org.graalvm.polyglot.proxy.ProxyObject
      Parameters:
      key - The member name to test.
      Returns:
      true when the member can be resolved.

    • putMember

      default void putMember(String key, org.graalvm.polyglot.Value value)
      Writes a member to the wrapped Python object.

      Python None is converted to Java null. Host objects that are themselves ValueCoercible instances are unwrapped to their Python value before assignment, and PooledValueCoercible instances are resolved in the target Python context so pooled event-loop objects are not mixed between contexts.

      Specified by:
      putMember in interface org.graalvm.polyglot.proxy.ProxyObject
      Parameters:
      key - The Python member name to write.
      value - The incoming polyglot value.

    • hostObject

      static @Nullable ValueCoercible hostObject(@Nullable org.graalvm.polyglot.Value value)
      Extracts a generated Java wrapper from a polyglot value when one is available.

      This method recognizes both direct host objects and Micronaut's synthetic HOST_OBJECT_MEMBER back-reference.

      Parameters:
      value - The polyglot value to inspect.
      Returns:
      The generated wrapper, or null when the value is not backed by a ValueCoercible.

    • hostObject

      static @Nullable ValueCoercible hostObject(@Nullable org.graalvm.polyglot.proxy.ProxyObject value)
      Extracts a generated Java wrapper from a proxy object when one is available.

      This overload is used when code already has a ProxyObject view and needs to inspect Micronaut's synthetic HOST_OBJECT_MEMBER without first wrapping it as a Value.

      Parameters:
      value - The proxy object to inspect.
      Returns:
      The generated wrapper, or null when the proxy does not expose one.

    • hostObject

      static @Nullable Object hostObject(@Nullable org.graalvm.polyglot.Value value, Class<?> targetType)
      Extracts a host object of the requested type from a polyglot value.

      The returned object may be a direct GraalPy host object or the generated Java wrapper recovered through HOST_OBJECT_MEMBER.

      Parameters:
      value - The polyglot value to inspect.
      targetType - The required host object type.
      Returns:
      The host object when it is assignable to targetType; otherwise null.

    • hostObject

      static @Nullable Object hostObject(@Nullable org.graalvm.polyglot.proxy.ProxyObject value, Class<?> targetType)
      Extracts a host object of the requested type from a proxy object.

      This method checks Micronaut's synthetic HOST_OBJECT_MEMBER and verifies the recovered host object before returning it.

      Parameters:
      value - The proxy object to inspect.
      targetType - The required host object type.
      Returns:
      The host object when it is assignable to targetType; otherwise null.

    • matchesArgument

      static boolean matchesArgument(org.graalvm.polyglot.Value value, Class<?> targetType)
      Match one Python argument against a Java parameter type without conversion.

      Runtime proxies expose all overloads for a Java method name through one Python callable. This quick check uses generated ExecutableMethod metadata and only boxes primitive types through ReflectionUtils; it deliberately avoids reflective probing of the generated proxy class while still letting Python-backed values expose their host wrapper via HOST_OBJECT_MEMBER.

      Parameters:
      value - The Python argument
      targetType - The Java parameter type
      Returns:
      Whether the argument can be passed to the generated method