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.

  • Field Details

    • HOST_OBJECT_MEMBER

      static final String HOST_OBJECT_MEMBER
      See Also:

    • AS_POLYGLOT_VALUE_MEMBER

      static final String AS_POLYGLOT_VALUE_MEMBER
      See Also:

    • PYTHON_OBJECT_MEMBER

      static final String PYTHON_OBJECT_MEMBER
      The member the Python view of a wrapper reads its Python object from, as opposed to the public AS_POLYGLOT_VALUE_MEMBER, which always answers with the object of the wrapper itself.

      The name is dunder-style so that Python does not mangle it inside the class body of the view, and carries the RUNTIME_MEMBER_PREFIX so that it stays out of member enumeration.

      See Also:

    • THROWABLE_MEMBERS

      static final List<String> THROWABLE_MEMBERS
      The accessors of the Java exception a generated exception wrapper exposes to Python.

    • RUNTIME_MEMBER_PREFIX

      static final String RUNTIME_MEMBER_PREFIX
      The prefix of the attributes the runtime stores on a Python object, hidden from member enumeration.
      See Also:

  • 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.

      A generated wrapper that does not hold a Python object yet creates one on the first call, so the value is never null: the default methods of this interface and the generated accessors read it without a null check.

      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. Three Micronaut-specific members are handled before delegating to Python: HOST_OBJECT_MEMBER exposes a private host reference used to recover the generated Java wrapper, AS_POLYGLOT_VALUE_MEMBER exposes a zero-argument callable that returns the wrapped Value of this wrapper, and PYTHON_OBJECT_MEMBER the callable the Python view of the wrapper reads, which answers with the object of the context the caller runs in. JavaBean-style generated accessor aliases are resolved after direct Python members, and a wrapper that is a Throwable exposes the accessors of the Java exception (getMessage(), getCause(), ...), so a Python exception handler reads the Java view of a Python exception that crossed Java.

      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.