Interface RuntimeTransportContext

public interface RuntimeTransportContext
Runtime services exposed to transport providers.

Implementations are thread-safe. Transport providers may call these methods concurrently from transport worker threads or virtual threads. The returned encoded values are owned by the caller.

  • Method Details

    • identity

      RuntimeIdentity identity()
      Returns the owning runtime identity.
      Returns:
      runtime identity

    • codec

      ValueCodec codec()
      Returns the runtime value codec.
      Returns:
      codec

    • encodeValue

      EncodedValue encodeValue(Object value, Class<?> declaredType)
      Encodes a value using runtime reference-passing policy.
      Parameters:
      value - Java value
      declaredType - declared Java type
      Returns:
      encoded value

    • decodeValue

      Object decodeValue(EncodedValue value, Class<?> expectedType)
      Decodes a value using runtime reference-passing policy.
      Parameters:
      value - encoded value
      expectedType - expected Java type
      Returns:
      decoded Java value

    • dispatch

      EncodedValue dispatch(ObjectRef target, MethodDescriptor method, List<EncodedValue> arguments, InvocationOptions options)
      Dispatches a generic invocation to a local exported object.
      Parameters:
      target - target object reference
      method - method descriptor
      arguments - encoded arguments
      options - invocation options
      Returns:
      encoded return value

    • dispatchTrusted

      default EncodedValue dispatchTrusted(ObjectRef target, MethodDescriptor method, List<EncodedValue> arguments, InvocationOptions options, SecurityContext trustedContext)
      Dispatches an invocation using identity established by a trusted transport or local boundary.

      Implementations must ignore authentication claims in InvocationOptions.metadata() and use trustedContext only when the caller is an authenticated transport or local in-process boundary. The default implementation falls back to untrusted dispatch for compatibility with existing providers.

      Parameters:
      target - target object reference
      method - method descriptor
      arguments - encoded arguments
      options - invocation options
      trustedContext - trusted peer context
      Returns:
      encoded return value

    • dispatchLogicalAsyncTrusted

      default EncodedValue dispatchLogicalAsyncTrusted(ObjectRef target, MethodDescriptor method, List<EncodedValue> arguments, InvocationOptions options, SecurityContext trustedContext, InvocationCancellation cancellation)
      Dispatches a versioned logical asynchronous result under authenticated transport ownership. Unsupported runtimes fail before decoding or target execution; providers must not fall back to legacy dispatch.
      Parameters:
      target - authoritative target
      method - complete erased method identity; the server verifies its generic result shape
      arguments - encoded arguments
      options - finite invocation budget
      trustedContext - authenticated peer
      cancellation - transport-owned cooperative cancellation registration
      Returns:
      encoded logical result after actual result/encoding completion

    • validateTarget

      default void validateTarget(ObjectRef target, String requiredInterface)
      Validates that a received reference names a live authoritative export.
      Parameters:
      target - target object reference received from a client
      requiredInterface - required interface name, or an empty string when no additional interface is required

    • describeTarget

      default List<String> describeTarget(ObjectRef target)
      Returns authoritative interfaces for a live exported target.
      Parameters:
      target - target object reference received from a client
      Returns:
      immutable authoritative interface names

    • exportCallback

      ObjectRef exportCallback(Object value, Class<?> declaredType)
      Creates or finds a local reference for a callback argument.
      Parameters:
      value - callback implementation
      declaredType - declared interface type
      Returns:
      exported object reference

    • releaseInvocationCallbacks

      default void releaseInvocationCallbacks(List<EncodedValue> encodedArguments)
      Releases automatic callback references exported for an invocation that did not complete or could not be admitted.

      Implementations must only release automatic callback exports owned by the current runtime. Successful callback registration may intentionally outlive the parent invocation so a remote endpoint can call the listener later; those automatic exports remain bounded by runtime-owned live callback limits and are closed with the owning runtime. Explicit long-lived exports are not automatic callback exports and remain available until their registration is closed.

      Parameters:
      encodedArguments - encoded invocation arguments to inspect

    • releaseFailedInvocationCallbacks

      @Deprecated(since="0.1.0", forRemoval=false) default void releaseFailedInvocationCallbacks(List<EncodedValue> encodedArguments)
      Deprecated.
      use releaseInvocationCallbacks(List) for failed, cancelled, timed-out, or admission-failed invocation cleanup
      Releases callback references that were exported for a failed invocation.
      Parameters:
      encodedArguments - encoded invocation arguments to inspect

    • executeOneWay

      default void executeOneWay(Runnable task)
      Submits a one-way invocation to runtime-owned bounded execution.
      Parameters:
      task - invocation task
      Throws:
      MiddlewareException - when the task cannot be admitted

    • proxyFor

      <T> T proxyFor(ObjectRef ref, Class<T> api)
      Creates a proxy for the supplied reference.
      Type Parameters:
      T - interface type
      Parameters:
      ref - target reference
      api - required Java interface
      Returns:
      proxy