Class Subscribe

java.lang.Object
org.mqtt4j.hato.Subscribe
public final class Subscribe extends Object

A request for one subscription. Shared filters use $share/{group}/{filter} syntax. The original filter, including a shared group, identifies duplicate subscriptions.

Instances are immutable values; each with method returns a copy with one setting changed. A setting left unchanged takes its default, which can depend on how the subscription receives messages.

Subscriptions support QoS 0, QoS 1, and QoS 2. The subscription options No Local, Retain As Published, and Retain Handling need MQTT 5.0: an MQTT 3.1.1 client refuses a request that changes any of them from its default with IllegalArgumentException.

  • Method Details

    • of

      public static Subscribe of(TopicFilter filter, Qos qos)
      Requests filter with qos as the maximum quality of service, the default acknowledgement mode, a buffer capacity of 1024, FailurePolicy.STOP, and the MQTT 5.0 defaults for the subscription options: No Local and Retain As Published off, and RetainHandling.SEND.
      Parameters:
      filter - the filter sent to the broker
      qos - the maximum quality of service requested
      Returns:
      the request
      Throws:
      IllegalArgumentException - 
      if shared syntax is invalid

    • withAckMode

      public Subscribe withAckMode(AckMode ackMode)
      Returns a copy that uses ackMode instead of the default.
      Parameters:
      ackMode - the acknowledgement mode
      Returns:
      a copy that uses ackMode instead of the default

    • withBufferCapacity

      public Subscribe withBufferCapacity(int bufferCapacity)
      Returns a copy with a different buffer capacity.
      Parameters:
      bufferCapacity - the maximum number of local deliveries this subscription holds at once
      Returns:
      a copy with a different buffer capacity
      Throws:
      IllegalArgumentException - 
      if `bufferCapacity` is not positive

    • withFailurePolicy

      public Subscribe withFailurePolicy(FailurePolicy failurePolicy)
      Returns a copy that handles handler failures with failurePolicy instead of FailurePolicy.STOP.
      Parameters:
      failurePolicy - what the subscription does when its handler throws
      Returns:
      a copy that handles handler failures with failurePolicy instead of FailurePolicy.STOP

    • withNoLocal

      public Subscribe withNoLocal(boolean noLocal)
      Returns a copy that asks the broker not to deliver this client's own publications to this subscription (the MQTT 5.0 No Local option), or to deliver them as usual.
      Parameters:
      noLocal - whether the broker withholds this client's own publications from this subscription
      Returns:
      a copy that asks the broker not to deliver this client's own publications to this subscription (the MQTT 5.0 No Local option), or to deliver them as usual
      Throws:
      IllegalArgumentException - 
      if `noLocal` is true for a shared subscription, which MQTT 5.0 does not allow

    • withRetainAsPublished

      public Subscribe withRetainAsPublished(boolean retainAsPublished)
      Returns a copy that asks the broker to keep the retain flag that each publisher set on the messages that it delivers to this subscription (the MQTT 5.0 Retain As Published option), or to clear it as usual; see MqttMessage.retain().
      Parameters:
      retainAsPublished - whether the broker keeps the publisher's retain flag on the messages that it delivers to this subscription
      Returns:
      a copy that asks the broker to keep the retain flag that each publisher set on the messages that it delivers to this subscription (the MQTT 5.0 Retain As Published option), or to clear it as usual; see MqttMessage.retain()

    • withRetainHandling

      public Subscribe withRetainHandling(RetainHandling retainHandling)
      Returns a copy that decides when the broker sends the matching retained messages as it makes this subscription (the MQTT 5.0 Retain Handling option).
      Parameters:
      retainHandling - when the broker sends the matching retained messages
      Returns:
      a copy that decides when the broker sends the matching retained messages as it makes this subscription (the MQTT 5.0 Retain Handling option)

    • filter

      public TopicFilter filter()
      Returns the filter sent to the broker.
      Returns:
      the filter sent to the broker

    • qos

      public Qos qos()
      Returns the maximum quality of service requested.
      Returns:
      the maximum quality of service requested

    • ackMode

      public Optional<AckMode> ackMode()
      Returns the acknowledgement mode: when this subscription permits acknowledgement of a QoS 1 or 2 delivery. Empty uses the default: AckMode.AFTER_HANDLER with a handler, or AckMode.ON_RECEIVE for pull and hand-off subscriptions.
      Returns:
      the acknowledgement mode: when this subscription permits acknowledgement of a QoS 1 or 2 delivery

    • bufferCapacity

      public int bufferCapacity()

      Returns the maximum number of local deliveries this subscription holds at once. Pull subscriptions count queued deliveries and QoS 1/2 MANUAL deliveries awaiting ack; ON_RECEIVE and QoS 0 release the slot at handoff. Hand-off subscriptions count deliveries waiting for their acceptor and release the slot when it accepts one, in either acknowledgement mode. Push subscriptions also count running handlers and deliveries whose PUBACK or PUBREC is pending; see AckMode. The client also bounds deliveries and bytes held across all of its subscriptions.

      What happens beyond these bounds depends on the QoS of the received message, which can exceed the requested one when another subscription of the client also matches. A QoS 1 or 2 message that exceeds any bound ends the connection. To stay within them, the client drops QoS 0 messages instead, possibly before a bound is reached, and the connection goes on; ClientStats.Receiving.dropped() counts the drops by reason. Which QoS 0 messages it drops, and when, is not part of this contract and may change between versions. A small capacity for QoS 0 subscriptions leaves room in the client's bounds for QoS 1 and 2 messages.

      Returns:
      the maximum number of local deliveries this subscription holds at once

    • failurePolicy

      public FailurePolicy failurePolicy()
      Returns what this subscription does when its handler throws; see FailurePolicy. A pull subscription has no handler and rejects FailurePolicy.SKIP.
      Returns:
      what this subscription does when its handler throws; see FailurePolicy

    • noLocal

      public boolean noLocal()
      Returns whether the broker withholds this client's own publications from this subscription.
      Returns:
      whether the broker withholds this client's own publications from this subscription

    • retainAsPublished

      public boolean retainAsPublished()
      Returns whether the broker keeps the publisher's retain flag on the messages that it delivers to this subscription.
      Returns:
      whether the broker keeps the publisher's retain flag on the messages that it delivers to this subscription

    • retainHandling

      public RetainHandling retainHandling()
      Returns the Retain Handling option: when the broker sends the matching retained messages as it makes this subscription.
      Returns:
      the Retain Handling option: when the broker sends the matching retained messages as it makes this subscription

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object