Package org.acemq.amqp.core

Class PublishOptions

java.lang.Object
org.acemq.amqp.core.PublishOptions
public final class PublishOptions extends Object
How a message should be published.

The defaults are the safe ones, and they are the defaults precisely because the unsafe versions are faster: messages are written to disk, and a message nothing is bound to receive is an error rather than a silence. Both can be turned off, deliberately and visibly, per publisher or per message. 


 // Telemetry: high volume, and losing some in a broker restart is fine.
 mq.publisher("metrics", "cpu.sample", Sample.class,
         PublishOptions.transientDelivery().expiringAfter(Duration.ofMinutes(5)));

 // A fan-out nobody may be listening to yet.
 mq.publisher("audit", "user.login", LoginEvent.class,
         PublishOptions.defaults().allowUnroutable());

Immutable: every method returns a new instance, so one held in a field cannot be changed under a thread that is publishing with it.

  • Method Details

    • defaults

      public static PublishOptions defaults()
      Returns:
      messages written to disk, unroutable messages reported as failures, and no expiry

    • transientDelivery

      public static PublishOptions transientDelivery()
      Messages the broker may keep in memory only.

      Faster, and lost when the broker restarts — including messages already sitting in a durable queue, because a transient message in a durable queue is still transient. Reasonable for telemetry, samples and cache invalidations, where the next message makes the last one irrelevant. Not reasonable for anything a person would notice the absence of.

      Note that a publisher confirm still means the broker accepted the message. It does not mean the message survived a restart, and with this set it very well might not have.

      Returns:
      options that let the broker skip the disk

    • allowUnroutable

      public PublishOptions allowUnroutable()
      Stops treating an unroutable message as a failure.

      By default a message that reaches the broker but matches no binding raises PublishFailedException, because that is nearly always a typo in a routing key or a queue nobody declared, and it is the single easiest way to lose messages while every log line looks healthy.

      Turn it off only where nothing being bound is genuinely expected: an audit fan-out with no subscribers yet, or an event nobody is required to consume. It is a real decision, and it makes the routing-key typo silent again for this publisher.

      Returns:
      options that accept unroutable messages

    • expiringAfter

      public PublishOptions expiringAfter(Duration expiration)
      Discards the message if it has not been consumed within the given time.

      Per-message time-to-live, applied by the broker. For messages that stop being worth delivering — a price quote, a session heartbeat, a cache invalidation for a key that has since changed twice.

      Expiry is not a guarantee of promptness: RabbitMQ removes an expired message when it reaches the head of the queue, so one sitting behind a backlog can outlive its time-to-live and still be discarded rather than delivered late. A consumer must not assume that whatever arrives is within its window.

      Parameters:
      expiration - how long the message stays worth delivering; must be positive
      Returns:
      options with that expiry

    • withPriority

      public PublishOptions withPriority(int priority)
      Publishes at the given priority.

      Priority is a property of the queue first: it does nothing unless the queue was declared with x-max-priority, and a broker that was not told a maximum ignores what a message asks for. Declare the queue with it and publish with this: 

      
 mq.declareQueue("work", QueueType.CLASSIC, Map.of("x-max-priority", 10));
 mq.publisher("", "work", Job.class)
         .with(PublishOptions.defaults().withPriority(9))
         .send(urgent);

      Priority reorders what is waiting, not what has already been handed to a consumer. With a large prefetch the urgent message queues behind work the consumer was already given, which is the usual reason priority "does not work" -- see ConsumerOptions.prefetch.

      Parameters:
      priority - priority to publish at; higher is more urgent, and must not be negative
      Returns:
      a copy publishing at that priority
      Throws:
      IllegalArgumentException - if the priority is negative

    • alwaysConfirmed

      public PublishOptions alwaysConfirmed()
      Confirms every publish and checks it for a return, even on a connection made withoutPublisherConfirms().

      What the library uses for everything it publishes on a caller's behalf — a pipeline hop, a scheduled delivery, an outbox record, a reply — because each settles something on the answer, and without a confirm the answer is always "routed". Use it for a publisher whose result you act on in the same way on a connection that otherwise skips confirms.

      Returns:
      options whose publishes are always confirmed

    • isAlwaysConfirmed

      public boolean isAlwaysConfirmed()
      Returns:
      whether every publish is confirmed whatever the connection's mode

    • persistent

      public boolean persistent()
      Returns:
      whether the broker is asked to write these messages to disk

    • mandatory

      public boolean mandatory()
      Returns:
      whether an unroutable message is reported as a failure

    • expiration

      public Optional<Duration> expiration()
      Returns:
      how long a message stays worth delivering, when a limit was set

    • priority

      public Optional<Integer> priority()
      Returns:
      the priority to publish at, if one was chosen

    • toString

      public String toString()
      Overrides:
      toString in class Object