Package org.apache.pulsar.client.api

Interface TypedMessageBuilder<T>

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

    Usage example: 

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

    • Method Detail

      • 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

        java.util.concurrent.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​(java.lang.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​(java.lang.String name,
                                java.lang.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​(java.util.Map<java.lang.String,​java.lang.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​(java.util.List<java.lang.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,
                                    java.util.concurrent.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