Interface MiddlewareRuntime

All Superinterfaces:
AutoCloseable
public interface MiddlewareRuntime extends AutoCloseable
Thread-safe public entry point for exporting and locating middleware objects.

Implementations own transport endpoints, registry bindings, heartbeat tasks, lifecycle hooks, and exported object maps. Public methods throw MiddlewareException with normalized error codes instead of raw reflection, registry, or transport failures.

The runtime is the owner of exported-object lifecycle. Calls may block on registry access, local lifecycle hooks, transport dispatch, or caller supplied deadlines. Security and authorization checks are evaluated before invocation, and status output must be redacted so principals, credentials, and sensitive metadata are not exposed. JPMS boundaries remain authoritative: exporting an object does not open internal packages or grant access to non-exported implementation classes.

  • Method Details

    • identity

      RuntimeIdentity identity()
      Returns this runtime's immutable identity.
      Returns:
      runtime identity

    • export

      <T> ObjectRegistration<T> export(String serviceName, T instance, Class<T> primaryInterface, ExportOptions options)
      Exports a Java object under a logical service name.
      Type Parameters:
      T - primary Java interface type
      Parameters:
      serviceName - logical service name
      instance - object instance
      primaryInterface - primary Java interface exposed remotely
      options - export options
      Returns:
      registration handle
      Throws:
      MiddlewareException - when arguments are invalid, lifecycle hooks fail, or registry/transport export fails

    • prepareExport

      <T> PreparedObjectRegistration<T> prepareExport(String serviceName, T instance, Class<T> primaryInterface, ExportOptions options)
      Prepares a Java object export without making it discoverable.

      The returned handle owns any lifecycle and transport-local state created during preparation. The object is not returned by list(String, List, Map, LookupOptions) and cannot be found by lookup(String, Class, LookupOptions) until PreparedObjectRegistration.commit() succeeds. This enables application activation code to prepare all declared services first and publish them only after readiness gates have closed. Callers must close every uncommitted prepared handle when any part of the publication group fails.

      Type Parameters:
      T - primary Java interface type
      Parameters:
      serviceName - logical service name
      instance - object instance
      primaryInterface - primary Java interface exposed remotely
      options - export options
      Returns:
      prepared registration handle
      Throws:
      MiddlewareException - when arguments are invalid, lifecycle hooks fail, transport preparation fails, or the runtime does not support prepared publication

    • commitPreparedExports

      List<ObjectRegistration<?>> commitPreparedExports(List<? extends PreparedObjectRegistration<?>> preparedExports)
      Commits a prepared export group as one publication operation.

      All supplied handles must have been returned by this runtime and must still be uncommitted. Implementations must validate the entire group before making any member visible through list(String, List, Map, LookupOptions), lookup(String, Class, LookupOptions), status snapshots, registry records, or heartbeats. If any mandatory publication step fails, all records and local publication state created for the group are rolled back before the method throws. Callers remain responsible for closing the prepared handles after a failed commit so transport-local preparation state and lifecycle ownership are released.

      The returned registration list preserves the order of the supplied prepared registrations. The method may block on registry publication and heartbeat scheduling, and failures are reported as normalized MiddlewareException instances.

      Parameters:
      preparedExports - prepared export handles to publish
      Returns:
      committed registration handles in input order
      Throws:
      MiddlewareException - when the group is empty, contains invalid handles, contains handles from another runtime, has already been closed or committed, or when publication fails

    • lookup

      <T> T lookup(String serviceName, Class<T> api, LookupOptions options)
      Looks up one object by service name and Java interface.
      Type Parameters:
      T - Java interface type
      Parameters:
      serviceName - logical service name
      api - required Java interface
      options - lookup options
      Returns:
      local instance, transport proxy, or HA proxy
      Throws:
      MiddlewareException - with NOT_FOUND, INTERFACE_MISMATCH, REGISTRY_UNAVAILABLE, or transport errors

    • list

      List<ObjectRef> list(String serviceName, List<String> interfaces, Map<String,String> requiredParams, LookupOptions options)
      Lists matching object references.
      Parameters:
      serviceName - logical service name
      interfaces - required interface names
      requiredParams - required metadata key/value pairs
      options - lookup options
      Returns:
      immutable list of matching references
      Throws:
      MiddlewareException - when registry access fails

    • reference

      default <T> T reference(ObjectRef reference, Class<T> contract, ProxyOptions options)
      Creates a proxy for one exact concrete reference without registry reselection or HA retry. Each proxy invocation retains normal transport/security behavior and its explicit budget; creating a reference does not grant authority or durable deduplication. Implementations that cannot provide exact-reference semantics fail closed for source compatibility.
      Type Parameters:
      T - ordinary business interface
      Parameters:
      reference - concrete selected identity
      contract - required interface exposed by reference
      options - per-call proxy budget and safe metadata
      Returns:
      exact-reference business proxy
      Throws:
      MiddlewareException - for unavailable support, invalid references or incompatible contracts

    • status

      RuntimeStatus status()
      Returns a read-only status snapshot.
      Returns:
      runtime status

    • close

      void close()
      Shuts the runtime down and releases owned resources. The method is idempotent.
      Specified by:
      close in interface AutoCloseable