Interface PreparedObjectRegistration<T>

Type Parameters:
T - primary Java interface type
All Superinterfaces:
AutoCloseable
public interface PreparedObjectRegistration<T> extends AutoCloseable
Prepared object export that is transport-ready but not discoverable.

A prepared registration is owned by the runtime that created it. Until commit() succeeds, the object reference returned by ref() is not present in runtime lookup/list results, is not bound in the registry, and is not heartbeat-maintained. The runtime may already have installed transport-local dispatch state needed to make a later commit inexpensive; callers must therefore close the prepared handle when activation or another publication transaction fails.

Instances are thread-safe when supplied by a runtime implementation. Closing an uncommitted handle rolls back transport state and lifecycle ownership. Closing after a successful commit closes the committed ObjectRegistration. The handle never exposes concrete transport implementation handles.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Rolls back the prepared export, or closes the committed registration when commit has already succeeded.
    ObjectRegistration<T>
    commit()
    Commits the prepared export into runtime lookup/list state and registry publication.
    T
    instance()
    Returns the local target instance owned by the runtime.
    ObjectRef
    ref()
    Returns the object reference allocated for the prepared export.
    default void
    setInvocationCompletionFactory(InvocationCompletionFactory factory)
    Installs trusted physical invocation ownership before publication.
    default void
    setReadiness(boolean ready, Duration validity)
    Sets host-owned readiness with a finite freshness bound, without changing export identity.
    default void
    setValueCodec(ValueCodec codec)
    Installs an immutable host-owned codec for this export before publication.

  • Method Details

    • ref

      ObjectRef ref()
      Returns the object reference allocated for the prepared export.
      Returns:
      object reference, not discoverable until commit

    • instance

      T instance()
      Returns the local target instance owned by the runtime.
      Returns:
      local target instance

    • setReadiness

      default void setReadiness(boolean ready, Duration validity)
      Sets host-owned readiness with a finite freshness bound, without changing export identity. Set initial false before commit to prevent a publication window. Only the owner receives this handle; invocation metadata cannot call this setter. Once enabled, expiry is unready even if the probe/heartbeat scheduler stops. Legacy exports which never opt in retain their existing unlimited readiness behavior. A false observation never becomes ready merely because it expires. Unsupported runtimes fail closed.
      Parameters:
      ready - latest trusted host readiness result
      validity - freshness duration from1millisecond through5minutes
      Throws:
      MiddlewareException - for unsupported runtimes, invalid validity or closed registrations

    • setInvocationCompletionFactory

      default void setInvocationCompletionFactory(InvocationCompletionFactory factory)
      Installs trusted physical invocation ownership before publication. The factory is local host state and is never serialized in export options. Unsupported runtimes fail closed; changing it after commit is forbidden.
      Parameters:
      factory - non-null host-owned invocation admission and lifetime factory
      Throws:
      MiddlewareException - if unsupported, closed or already committed

    • setValueCodec

      default void setValueCodec(ValueCodec codec)
      Installs an immutable host-owned codec for this export before publication. The codec and its verified schema allowlist are local state, never wire metadata. Both inbound arguments and outbound results use it; local lookup must preserve the same dispatch boundary. The host must supply a thread-safe codec without a mutable global application class registry.
      Parameters:
      codec - non-null trusted export codec
      Throws:
      MiddlewareException - if unsupported, closed, already installed or committed

    • commit

      ObjectRegistration<T> commit()
      Commits the prepared export into runtime lookup/list state and registry publication.
      Returns:
      committed registration handle
      Throws:
      MiddlewareException - when registry publication, heartbeat setup, or runtime lifecycle ownership fails

    • close

      void close()
      Rolls back the prepared export, or closes the committed registration when commit has already succeeded. The method is idempotent.
      Specified by:
      close in interface AutoCloseable