Interface TransportProvider

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
StreamingTransportProvider
public interface TransportProvider extends AutoCloseable
Stable SPI for middleware transports.

Implementations must be thread-safe after start(RuntimeTransportContext). A provider is owned by exactly one runtime instance in Phase 1. Providers must wrap low-level failures in middleware exceptions.

  • Method Details

    • id

      String id()
      Returns the stable transport identifier.
      Returns:
      transport id

    • start

      TransportEndpoint start(RuntimeTransportContext context)
      Starts this provider for one runtime.
      Parameters:
      context - runtime context
      Returns:
      endpoint descriptor

    • export

      ExportedObject export(ObjectRef ref, Object target, ExportDescriptor descriptor)
      Exports one local object through this transport.
      Parameters:
      ref - object reference
      target - local target
      descriptor - export descriptor
      Returns:
      exported object handle

    • unexport

      void unexport(ObjectRef ref)
      Unexports one object. The method is idempotent.
      Parameters:
      ref - object reference

    • invoke

      Object invoke(ObjectRef target, MethodDescriptor method, List<EncodedValue> arguments, InvocationOptions options)
      Invokes a method on a target reference.
      Parameters:
      target - target reference
      method - method descriptor
      arguments - encoded arguments
      options - invocation options
      Returns:
      decoded return value

    • invoke

      default Object invoke(ObjectRef target, MethodDescriptor method, List<EncodedValue> arguments, InvocationOptions options, Class<?> returnType)
      Invokes with the exact return class established from the local Java contract. This host-local token preserves an application classloader's schema allowlist; it is never read from the reply or loaded from a wire class name. Descriptor-only calls retain their transport's documented class-resolution fallback. Providers supporting isolated application schemas override this method and decode local and remote replies with this exact token.
      Parameters:
      target - pinned reference
      method - verified method identity
      arguments - bounded encoded arguments
      options - remaining invocation budget
      returnType - exact local declared return class, matching the descriptor
      Returns:
      decoded value
      Throws:
      MiddlewareException - for a mismatched local contract token

    • invokeAsync

      default CompletableFuture<Object> invokeAsync(ObjectRef target, MethodDescriptor method, List<EncodedValue> arguments, InvocationOptions options, AsyncMethodDescriptor result)
      Invokes the dedicated logical asynchronous protocol without falling back to a legacy method. Implementations return promptly and do not encode or serialize a future object.
      Parameters:
      target - pinned target reference
      method - complete erased method identity
      arguments - immutable encoded arguments
      options - remaining total invocation budget
      result - validated concrete logical result shape
      Returns:
      cancellable reply stage; cancellation does not prove physical completion or undo

    • createProxy

      <T> T createProxy(ObjectRef ref, Class<T> api, ProxyOptions options)
      Creates a Java proxy for a target reference.
      Type Parameters:
      T - interface type
      Parameters:
      ref - target reference
      api - Java interface
      options - proxy options
      Returns:
      proxy implementing api

    • close

      void close()
      Closes provider-owned resources.
      Specified by:
      close in interface AutoCloseable