Package org.apache.pulsar.client.api

Interface TypedMessageBuilder<T>

All Superinterfaces:
Serializable
@Public @Stable public interface TypedMessageBuilder<T> extends Serializable
Message builder that constructs a message to be published through a producer.

Usage example: 


 producer.newMessage().key(myKey).value(myValue).send();

  • Field Details

  • Method Details

    • send

      MessageId send() throws PulsarClientException
      Send a message synchronously.

      This method will block until the message is successfully published and returns the MessageId assigned by the broker to the published message.

      Example: 

      
 MessageId msgId = producer.newMessage()
                  .key(myKey)
                  .value(myValue)
                  .send();
 System.out.println("Published message: " + msgId);
      Returns:
      the MessageId assigned by the broker to the published message.
      Throws:
      PulsarClientException

    • sendAsync

      CompletableFuture<MessageId> sendAsync()
      Send a message asynchronously

      This method returns a future that can be used to track the completion of the send operation and yields the MessageId assigned by the broker to the published message.

      Example: 

       producer.newMessage()
                  .value(myValue)
                  .sendAsync().thenAccept(messageId -> {
    System.out.println("Published message: " + messageId);
 }).exceptionally(e -> {
    System.out.println("Failed to publish " + e);
    return null;
 });

      When the producer queue is full, by default this method will complete the future with an exception PulsarClientException.ProducerQueueIsFullError

      See ProducerBuilder.maxPendingMessages(int) to configure the producer queue size and ProducerBuilder.blockIfQueueFull(boolean) to change the blocking behavior.

      Returns:
      a future that can be used to track when the message will have been safely persisted

    • key

      TypedMessageBuilder<T> key(String key)
      Sets the key of the message for routing policy.
      Parameters:
      key - the partitioning key for the message
      Returns:
      the message builder instance

    • keyBytes

      TypedMessageBuilder<T> keyBytes(byte[] key)
      Sets the bytes of the key of the message for routing policy. Internally the bytes will be base64 encoded.
      Parameters:
      key - routing key for message, in byte array form
      Returns:
      the message builder instance

    • orderingKey

      TypedMessageBuilder<T> orderingKey(byte[] orderingKey)
      Sets the ordering key of the message for message dispatch in SubscriptionType.Key_Shared mode. Partition key Will be used if ordering key not specified.
      Parameters:
      orderingKey - the ordering key for the message
      Returns:
      the message builder instance

    • value

      TypedMessageBuilder<T> value(T value)
      Set a domain object on the message.
      Parameters:
      value - the domain object
      Returns:
      the message builder instance

    • property

      TypedMessageBuilder<T> property(String name, String value)
      Sets a new property on a message.
      Parameters:
      name - the name of the property
      value - the associated value
      Returns:
      the message builder instance

    • properties

      TypedMessageBuilder<T> properties(Map<String,String> properties)
      Add all the properties in the provided map.
      Returns:
      the message builder instance

    • eventTime

      TypedMessageBuilder<T> eventTime(long timestamp)
      Set the event time for a given message.

      Applications can retrieve the event time by calling Message.getEventTime().

      Note: currently pulsar doesn't support event-time based index. so the subscribers can't seek the messages by event time.

      Returns:
      the message builder instance

    • sequenceId

      TypedMessageBuilder<T> sequenceId(long sequenceId)
      Specify a custom sequence id for the message being published.

      The sequence id can be used for deduplication purposes and it needs to follow these rules:

      1. sequenceId >= 0
      2. Sequence id for a message needs to be greater than sequence id for earlier messages: sequenceId(N+1) > sequenceId(N)
      3. It's not necessary for sequence ids to be consecutive. There can be holes between messages. Eg. the sequenceId could represent an offset or a cumulative size.
      Parameters:
      sequenceId - the sequence id to assign to the current message
      Returns:
      the message builder instance

    • replicationClusters

      TypedMessageBuilder<T> replicationClusters(List<String> clusters)
      Override the geo-replication clusters for this message.
      Parameters:
      clusters - the list of clusters.
      Returns:
      the message builder instance

    • disableReplication

      TypedMessageBuilder<T> disableReplication()
      Disable geo-replication for this message.
      Returns:
      the message builder instance

    • deliverAt

      TypedMessageBuilder<T> deliverAt(long timestamp)
      Deliver the message only at or after the specified absolute timestamp.

      The timestamp is milliseconds and based on UTC (eg: System.currentTimeMillis().

      Note: messages are only delivered with delay when a consumer is consuming through a SubscriptionType.Shared subscription. With other subscription types, the messages will still be delivered immediately.

      Parameters:
      timestamp - absolute timestamp indicating when the message should be delivered to consumers
      Returns:
      the message builder instance

    • deliverAfter

      TypedMessageBuilder<T> deliverAfter(long delay, TimeUnit unit)
      Request to deliver the message only after the specified relative delay.

      Note: messages are only delivered with delay when a consumer is consuming through a SubscriptionType.Shared subscription. With other subscription types, the messages will still be delivered immediately.

      Parameters:
      delay - the amount of delay before the message will be delivered
      unit - the time unit for the delay
      Returns:
      the message builder instance

    • loadConf

      TypedMessageBuilder<T> loadConf(Map<String,Object> config)
      Configure the TypedMessageBuilder from a config map, as an alternative compared to call the individual builder methods.

      The "value" of the message itself cannot be set on the config map.

      Example: 

      
 Map<String, Object> conf = new HashMap<>();
 conf.put("key", "my-key");
 conf.put("eventTime", System.currentTimeMillis());

 producer.newMessage()
             .value("my-message")
             .loadConf(conf)
             .send();

      The available options are:

      Constant Name Type Doc
      CONF_KEY key String key(String)
      CONF_PROPERTIES properties Map<String,String> properties(Map)
      CONF_EVENT_TIME eventTime long eventTime(long)
      CONF_SEQUENCE_ID sequenceId long sequenceId(long)
      CONF_REPLICATION_CLUSTERS replicationClusters List<String> replicationClusters(List)
      CONF_DISABLE_REPLICATION disableReplication boolean disableReplication()
      CONF_DELIVERY_AFTER_SECONDS deliverAfterSeconds long deliverAfter(long, TimeUnit)
      CONF_DELIVERY_AT deliverAt long deliverAt(long)
      Parameters:
      config - a map with the configuration options for the message
      Returns:
      the message builder instance