org.apache.pulsar.client.api.TypedMessageBuilder Maven / Gradle / Ivy
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.pulsar.client.api;
import java.io.Serializable;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
import org.apache.pulsar.common.classification.InterfaceAudience;
import org.apache.pulsar.common.classification.InterfaceStability;
/**
* Message builder that constructs a message to be published through a producer.
*
* Usage example:
*
* producer.newMessage().key(myKey).value(myValue).send();
*
*/
@InterfaceAudience.Public
@InterfaceStability.Stable
public interface TypedMessageBuilder extends Serializable {
/**
* Send a message synchronously.
*
* This method will block until the message is successfully published and returns the
* {@link MessageId} assigned by the broker to the published message.
*
*
Example:
*
*
{@code
* MessageId msgId = producer.newMessage()
* .key(myKey)
* .value(myValue)
* .send();
* System.out.println("Published message: " + msgId);
* }
*
* @return the {@link MessageId} assigned by the broker to the published message.
*/
MessageId send() throws PulsarClientException;
/**
* Send a message asynchronously
*
* This method returns a future that can be used to track the completion of the send operation and yields the
* {@link 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
* {@link PulsarClientException.ProducerQueueIsFullError}
*
*
See {@link ProducerBuilder#maxPendingMessages(int)} to configure the producer queue size and
* {@link ProducerBuilder#blockIfQueueFull(boolean)} to change the blocking behavior.
*
* @return a future that can be used to track when the message will have been safely persisted
*/
CompletableFuture sendAsync();
/**
* Sets the key of the message for routing policy.
*
* @param key the partitioning key for the message
* @return the message builder instance
*/
TypedMessageBuilder key(String key);
/**
* Sets the bytes of the key of the message for routing policy.
* Internally the bytes will be base64 encoded.
*
* @param key routing key for message, in byte array form
* @return the message builder instance
*/
TypedMessageBuilder keyBytes(byte[] key);
/**
* Sets the ordering key of the message for message dispatch in {@link SubscriptionType#Key_Shared} mode.
* Partition key Will be used if ordering key not specified.
*
* @param orderingKey the ordering key for the message
* @return the message builder instance
*/
TypedMessageBuilder orderingKey(byte[] orderingKey);
/**
* Set a domain object on the message.
*
* @param value
* the domain object
* @return the message builder instance
*/
TypedMessageBuilder value(T value);
/**
* Sets a new property on a message.
*
* @param name
* the name of the property
* @param value
* the associated value
* @return the message builder instance
*/
TypedMessageBuilder property(String name, String value);
/**
* Add all the properties in the provided map.
* @return the message builder instance
*/
TypedMessageBuilder properties(Map properties);
/**
* Set the event time for a given message.
*
* Applications can retrieve the event time by calling {@link Message#getEventTime()}.
*
*
Note: currently pulsar doesn't support event-time based index. so the subscribers
* can't seek the messages by event time.
* @return the message builder instance
*/
TypedMessageBuilder eventTime(long timestamp);
/**
* 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:
*
* sequenceId >= 0
* - Sequence id for a message needs to be greater than sequence id for earlier messages:
*
sequenceId(N+1) > sequenceId(N)
* - 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.
*
*
* @param sequenceId
* the sequence id to assign to the current message
* @return the message builder instance
*/
TypedMessageBuilder sequenceId(long sequenceId);
/**
* Override the geo-replication clusters for this message.
*
* @param clusters the list of clusters.
* @return the message builder instance
*/
TypedMessageBuilder replicationClusters(List clusters);
/**
* Disable geo-replication for this message.
*
* @return the message builder instance
*/
TypedMessageBuilder disableReplication();
/**
* Deliver the message only at or after the specified absolute timestamp.
*
* The timestamp is milliseconds and based on UTC (eg: {@link System#currentTimeMillis()}.
*
*
Note: messages are only delivered with delay when a consumer is consuming
* through a {@link SubscriptionType#Shared} subscription. With other subscription
* types, the messages will still be delivered immediately.
*
* @param timestamp
* absolute timestamp indicating when the message should be delivered to consumers
* @return the message builder instance
*/
TypedMessageBuilder deliverAt(long timestamp);
/**
* 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 {@link SubscriptionType#Shared} subscription. With other subscription
* types, the messages will still be delivered immediately.
*
* @param delay
* the amount of delay before the message will be delivered
* @param unit
* the time unit for the delay
* @return the message builder instance
*/
TypedMessageBuilder deliverAfter(long delay, TimeUnit unit);
/**
* Configure the {@link 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:
*
*
{@code
* Map 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
*
*
* {@link #CONF_KEY}
* {@code key}
* {@code String}
* {@link #key(String)}
*
*
* {@link #CONF_PROPERTIES}
* {@code properties}
* {@code Map}
* {@link #properties(Map)}
*
*
* {@link #CONF_EVENT_TIME}
* {@code eventTime}
* {@code long}
* {@link #eventTime(long)}
*
*
* {@link #CONF_SEQUENCE_ID}
* {@code sequenceId}
* {@code long}
* {@link #sequenceId(long)}
*
*
* {@link #CONF_REPLICATION_CLUSTERS}
* {@code replicationClusters}
* {@code List}
* {@link #replicationClusters(List)}
*
*
* {@link #CONF_DISABLE_REPLICATION}
* {@code disableReplication}
* {@code boolean}
* {@link #disableReplication()}
*
*
* {@link #CONF_DELIVERY_AFTER_SECONDS}
* {@code deliverAfterSeconds}
* {@code long}
* {@link #deliverAfter(long, TimeUnit)}
*
*
* {@link #CONF_DELIVERY_AT}
* {@code deliverAt}
* {@code long}
* {@link #deliverAt(long)}
*
*
*
* @param config a map with the configuration options for the message
* @return the message builder instance
*/
TypedMessageBuilder loadConf(Map config);
String CONF_KEY = "key";
String CONF_PROPERTIES = "properties";
String CONF_EVENT_TIME = "eventTime";
String CONF_SEQUENCE_ID = "sequenceId";
String CONF_REPLICATION_CLUSTERS = "replicationClusters";
String CONF_DISABLE_REPLICATION = "disableReplication";
String CONF_DELIVERY_AFTER_SECONDS = "deliverAfterSeconds";
String CONF_DELIVERY_AT = "deliverAt";
}