Class MessageConnector

java.lang.Object
org.eclipse.net4j.util.event.Notifier
org.eclipse.net4j.util.lifecycle.Lifecycle
org.eclipse.net4j.util.lifecycle.ShareableLifecycle
org.eclipse.net4j.util.container.Container<IChannel>
All Implemented Interfaces:
IBufferProvider, IChannelMultiplexer, IConnector, ILocationAware, ITransportConfigAware, org.eclipse.net4j.util.collection.Closeable, org.eclipse.net4j.util.concurrent.IExecutorServiceProvider, org.eclipse.net4j.util.container.IContainer<IChannel>, org.eclipse.net4j.util.event.INotifier, org.eclipse.net4j.util.event.INotifier.INotifier2, org.eclipse.net4j.util.lifecycle.IDeactivateable, org.eclipse.net4j.util.lifecycle.ILifecycle, org.eclipse.net4j.util.lifecycle.ILifecycle.DeferrableActivation, org.eclipse.net4j.util.properties.IPropertiesContainer, org.eclipse.net4j.util.security.INegotiatorAware, org.eclipse.net4j.util.security.IUserAware, InternalChannelMultiplexer, InternalConnector, InverseCloseable

public class MessageConnector extends SchedulingConnector
Multiplexes logical Net4j channels over an operator supplied asynchronous message connection. The inherited SchedulingConnector scheduler selects buffers from the channels' send queues; this connector advances that scheduled work to an MessageConnector.IMessageConnection provider, which owns the transport and reports asynchronous send completion. A provider may represent either an outgoing client connection or a server-side connection accepted by an independently managed server.

The connector submits at most one send transaction at a time. Scheduler completion means that a selected channel's queue head has been consumed by the connector; provider acceptance is a separate event, and an accepted buffer remains pinned until the provider's terminal callback proves that it no longer accesses the storage. The send pump serializes this progression without creating another queue or scheduler. A rejected send retains no provider borrow and waits for a writable notification before retrying.

Incoming messages use one unit of provider demand at a time. Accepted frames enter a connection-ordered ingress queue, then per-channel serial queues so a blocking handler on one channel does not stall another. Receive demand is replenished after ingress acceptance, independently of handler completion and buffer release. The connector retains provider storage without copying within a per-activation byte budget, then copies under a second byte budget; exhausting both fails the connection. Activation generations identify callbacks and send records belonging to a particular provider binding, so stale callbacks cannot advance a later connection. Shutdown detaches accepted sends but cannot reclaim their buffers until terminal completion; aborting a connection does not itself end a provider's borrow.

Since:
4.23
Author:
Eike Stepper
  • Constructor Details

    • MessageConnector

      public MessageConnector(long zeroCopyReceiveBudgetBytes, long copyReceiveBudgetBytes)
      Creates a message connector with bounded per-activation receive storage budgets.

      The default budgets allow one megabyte of outstanding zero-copy storage and four megabytes of copied receive storage per connection. When the zero-copy budget is full, incoming messages are copied while copy budget remains. Exhausting both budgets fails the connection.

      Parameters:
      zeroCopyReceiveBudgetBytes - maximum bytes retained from provider-owned receive storage
      copyReceiveBudgetBytes - maximum bytes retained in copied receive storage
      Throws:
      IllegalArgumentException - if either budget is negative
      Since:
      4.23
    • MessageConnector

      public MessageConnector()
      Creates a message connector with the default per-connection receive budgets.
      Since:
      4.23
  • Method Details

    • setConnection

      public final void setConnection(MessageConnector.IMessageConnection connection)
      Sets the provider connection before activation. The supplied connection may initiate a client connection or attach to an already accepted server connection.
      Parameters:
      connection - the provider connection to bind
    • setState

      public void setState(ConnectorState newState) throws ConnectorException
      Updates this connector's transport and negotiation state. A ConnectorState.CONNECTED transition is accepted only for the current ready provider generation and is arbitrated with deferred activation failure; other state transitions use the inherited connector behavior.
      Overrides:
      setState in class Connector
      Parameters:
      newState - the state to publish
      Throws:
      ConnectorException - if a connector operation required by the transition fails
    • getLocation

      public final ILocationAware.Location getLocation()
      Returns the configured client or server role used for signed Net4j channel identifiers.
      Specified by:
      getLocation in interface ILocationAware
      Overrides:
      getLocation in class Connector
      Returns:
      this connector's configured location
      Since:
      4.23
    • setLocation

      public final void setLocation(ILocationAware.Location location)
      Sets whether this connector represents a Net4j client or a server-side accepted connection. The server itself remains owned and managed by its provider.
      Parameters:
      location - ILocationAware.Location#CLIENT for an outgoing client, or ILocationAware.Location#SERVER for an accepted server connection
      Since:
      4.23
    • fireElementAddedEvent

      public void fireElementAddedEvent(IChannel channel)
      Routes queued receive frames after a channel has been added to the multiplexer. The map update occurs before this container event, so a dependent data frame can resolve its channel even if protocol connection setup continues with a nested signal.
      Overrides:
      fireElementAddedEvent in class org.eclipse.net4j.util.container.Container<IChannel>
      Parameters:
      channel - channel registered with this connector
    • fireElementRemovedEvent

      public void fireElementRemovedEvent(IChannel channel)
      Removes a channel's receive queue after the multiplexer has removed it, releasing any frames that can no longer be delivered.
      Overrides:
      fireElementRemovedEvent in class org.eclipse.net4j.util.container.Container<IChannel>
      Parameters:
      channel - channel removed from this connector
    • closeGracefully

      public final void closeGracefully()
      Drains currently queued Net4j messages and then requests graceful local closure of the underlying connection. Callers should stop producing new messages before invoking this method.
    • onSendingRequired

      protected void onSendingRequired()
      Description copied from class: SchedulingConnector
      Called when the scheduler transitions from idle to having pending work. Implementations should arrange a send attempt without blocking the producer that enqueued the buffer. The hook runs outside the scheduling lifecycle lock, so it must only arrange asynchronous work and must not perform transport I/O or block.
      Specified by:
      onSendingRequired in class SchedulingConnector
    • onSendingNoLongerRequired

      protected void onSendingNoLongerRequired()
      Description copied from class: SchedulingConnector
      Called when the scheduler becomes idle. Implementations should asynchronously stop requesting transport write readiness without performing transport I/O or blocking.
      Overrides:
      onSendingNoLongerRequired in class SchedulingConnector
    • createNegotiationContext

      protected org.eclipse.net4j.util.security.INegotiationContext createNegotiationContext()
      Specified by:
      createNegotiationContext in class SchedulingConnector
    • doBeforeActivate

      protected void doBeforeActivate() throws Exception
      Overrides:
      doBeforeActivate in class Connector
      Throws:
      Exception
    • doActivate

      protected void doActivate() throws Exception
      Overrides:
      doActivate in class SchedulingConnector
      Throws:
      Exception
    • doDeactivate

      protected void doDeactivate() throws Exception
      Overrides:
      doDeactivate in class SchedulingConnector
      Throws:
      Exception
    • doCancelActivation

      protected void doCancelActivation()
      Overrides:
      doCancelActivation in class org.eclipse.net4j.util.lifecycle.Lifecycle
    • terminatePendingActivation

      protected final void terminatePendingActivation()
      Ends a deferred activation when its owner explicitly aborts the provider connection. The method arbitrates against readiness and negotiation completion, detaches the current provider generation, and completes the lifecycle attempt as failed. It is safe to call after a provider has already reported closure and does not depend on MessageConnector.IMessageConnection.abort() producing a callback.
      Since:
      4.23
    • onActivationFailed

      protected void onActivationFailed()
      Called after a provider terminates while this connector is still undergoing deferred activation. Subclasses that are tracked by an owner can remove themselves from that owner's registry here because the failed deferred activation does not publish a normal DEACTIVATED lifecycle event.
      Since:
      4.23