Interface ConnectorDeliveryReservation

All Superinterfaces:
AutoCloseable
public interface ConnectorDeliveryReservation extends AutoCloseable
Pending message-count capacity reserved by an incoming connector before it acquires transport data.

A connector must reserve the maximum delivery it may retain before polling, reading, or otherwise accepting that delivery from its transport. The actual delivery supplied to start(MessageBatch), tryStart(MessageBatch), startFailed(MessageBatch, RuntimeException), or tryStartFailed(MessageBatch, RuntimeException) must not exceed the reserved message count. Starting atomically transfers the actual count from pending capacity to in-flight capacity and releases unused reservation capacity.

A reservation has one owner and one terminal transition: it is either started once, started with a pre-dispatch failure once, or closed. Closing is idempotent and releases capacity exactly once. After a successful start, ownership transfers to the returned ConnectorDelivery; closing this reservation no longer releases the delivery lease.

Each started connector delivery runs in a fresh Helidon context. The connector source thread's context is not inherited by application handlers, processors, interceptors, routes, or outgoing connectors.

  • Method Details

    • start

      ConnectorDelivery start(MessageBatch<?> batch)
      Start a retained connector delivery, waiting for execution admission when necessary.

      Capacity-wait time spent acquiring this reservation and starting it shares the channel's single admission timeout budget. Time spent by the connector acquiring transport data between those phases is excluded. The retained lease covers the supplied batch and subsets created through MessageBatch.subset(List). Rebuilt batches and replacement envelopes require separate admission.

      Parameters:
      batch - complete retained delivery
      Returns:
      admitted delivery task and settlement lease bound to batch by the structured-failure alignment contract
      Throws:
      MessagingRejectedException - if the delivery cannot be admitted
      IllegalStateException - if this reservation was already started or another start is in progress

    • startFailed

      default ConnectorDelivery startFailed(MessageBatch<?> batch, RuntimeException failure)
      Start a retained connector delivery whose transport-to-message mapping failed before dispatch.

      Runtime implementations can apply the channel failure policy to failed items without invoking application handlers for those items. The runtime cannot repeat transport mapping because it does not own the native transport record or mapper. Bounded policies retain their configured failure-attempt accounting; an unlimited policy treats the mapping failure as exhausted after its initial attempt so that the returned delivery always terminates.

      A structured BatchDeliveryException aligned to batch can identify unmappable items as BatchItemStatus.FAILED or BatchItemStatus.INDETERMINATE and mapped but undispatched siblings as BatchItemStatus.NOT_ATTEMPTED. The runtime settles the failed subset first, then dispatches the deferred subset only after successful drop or dead-letter settlement. An undispatched item must not be marked BatchItemStatus.SUCCEEDED.

      The default implementation closes this reservation and rethrows the supplied failure so implementations compiled against an earlier version fail safely instead of dispatching an invalid batch.

      Parameters:
      batch - retained delivery metadata used for failure accounting, drop, or dead-letter handling
      failure - pre-dispatch mapping failure
      Returns:
      admitted delivery task and settlement lease bound to batch by the structured-failure alignment contract
      Throws:
      RuntimeException - the supplied failure when this operation is not implemented by the runtime

    • tryStart

      Optional<ConnectorDelivery> tryStart(MessageBatch<?> batch)
      Attempt to start a retained connector delivery without waiting.

      The retained lease covers the supplied batch and subsets created through MessageBatch.subset(List). Rebuilt batches and replacement envelopes require separate admission.

      Parameters:
      batch - complete retained delivery
      Returns:
      admitted delivery task bound to batch by the structured-failure alignment contract, or empty when in-flight capacity is currently unavailable
      Throws:
      MessagingRejectedException - if the delivery exceeds this reservation or the reservation is unavailable
      IllegalStateException - if this reservation was already started or another start is in progress

    • tryStartFailed

      default Optional<ConnectorDelivery> tryStartFailed(MessageBatch<?> batch, RuntimeException failure)
      Attempt to start a retained connector delivery with a pre-dispatch mapping failure without waiting.

      Runtime implementations apply the same failure-policy and structured-outcome semantics as startFailed(MessageBatch, RuntimeException). Unlike that method, this operation returns empty when in-flight capacity is currently unavailable, leaving the reservation available for another start attempt.

      The default implementation closes this reservation and rethrows the supplied failure so implementations compiled against an earlier version fail safely instead of dispatching an invalid batch.

      Parameters:
      batch - retained delivery metadata used for failure accounting, drop, or dead-letter handling
      failure - pre-dispatch mapping failure
      Returns:
      admitted delivery task and settlement lease, or empty when in-flight capacity is currently unavailable
      Throws:
      RuntimeException - the supplied failure when this operation is not implemented by the runtime
      MessagingRejectedException - if the delivery exceeds this reservation or the reservation is unavailable
      IllegalStateException - if this reservation was already started or another start is in progress

    • close

      void close()
      Close an unstarted reservation and release its pending capacity.

      This method is idempotent. After a successful start the returned ConnectorDelivery owns the capacity.

      Specified by:
      close in interface AutoCloseable