pulsar-client-api/src/main/java/org/apache/pulsar/client/api/Message.java - pulsar - Git at Google

 /**
  * 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.util.Map;
 import java.util.Optional;
 import org.apache.pulsar.common.api.EncryptionContext;
 import org.apache.pulsar.common.classification.InterfaceAudience;
 import org.apache.pulsar.common.classification.InterfaceStability;

 /**
  * The message abstraction used in Pulsar.
  */
 @InterfaceAudience.Public
 @InterfaceStability.Stable
 public interface Message<T> {

     /**
      * Return the properties attached to the message.
      *
      * <p>Properties are application defined key/value pairs that will be attached to the message.
      *
      * @return an unmodifiable view of the properties map
      */
     Map<String, String> getProperties();

     /**
      * Check whether the message has a specific property attached.
      *
      * @param name the name of the property to check
      * @return true if the message has the specified property and false if the properties is not defined
      */
     boolean hasProperty(String name);

     /**
      * Get the value of a specific property.
      *
      * @param name the name of the property
      * @return the value of the property or null if the property was not defined
      */
     String getProperty(String name);

     /**
      * Get the raw payload of the message.
      *
      * <p>Even when using the Schema and type-safe API, an application
      * has access to the underlying raw message payload.
      *
      * @return the byte array with the message payload
      */
     byte[] getData();

     /**
      * Get the uncompressed message payload size in bytes.
      *
      * @return size in bytes.
      */
     int size();

     /**
      * Get the de-serialized value of the message, according the configured {@link Schema}.
      *
      * @return the deserialized value of the message
      */
     T getValue();

     /**
      * Get the unique message ID associated with this message.
      *
      * <p>The message id can be used to univocally refer to a message without having the keep
      * the entire payload in memory.
      *
      * <p>Only messages received from the consumer will have a message id assigned.
      *
      * @return the message id null if this message was not received by this client instance
      */
     MessageId getMessageId();

     /**
      * Get the publish time of this message. The publish time is the timestamp that a client publish the message.
      *
      * @return publish time of this message.
      * @see #getEventTime()
      */
     long getPublishTime();

     /**
      * Get the event time associated with this message. It is typically set by the applications via
      * {@link MessageBuilder#setEventTime(long)}.
      *
      * <p>If there isn't any event time associated with this event, it will return 0.
      *
      * @see MessageBuilder#setEventTime(long)
      * @since 1.20.0
      * @return the message event time or 0 if event time wasn't set
      */
     long getEventTime();

     /**
      * Get the sequence id associated with this message. It is typically set by the applications via
      * {@link MessageBuilder#setSequenceId(long)}.
      *
      * @return sequence id associated with this message.
      * @see MessageBuilder#setEventTime(long)
      * @since 1.22.0
      */
     long getSequenceId();

     /**
      * Get the producer name who produced this message.
      *
      * @return producer name who produced this message, null if producer name is not set.
      * @since 1.22.0
      */
     String getProducerName();

     /**
      * Check whether the message has a key.
      *
      * @return true if the key was set while creating the message and false if the key was not set
      * while creating the message
      */
     boolean hasKey();

     /**
      * Get the key of the message.
      *
      * @return the key of the message
      */
     String getKey();

     /**
      * Check whether the key has been base64 encoded.
      *
      * @return true if the key is base64 encoded, false otherwise
      */
     boolean hasBase64EncodedKey();

     /**
      * Get bytes in key. If the key has been base64 encoded, it is decoded before being returned.
      * Otherwise, if the key is a plain string, this method returns the UTF_8 encoded bytes of the string.
      * @return the key in byte[] form
      */
     byte[] getKeyBytes();

     /**
      * Check whether the message has a ordering key.
      *
      * @return true if the ordering key was set while creating the message
      *         false if the ordering key was not set while creating the message
      */
     boolean hasOrderingKey();

     /**
      * Get the ordering key of the message.
      *
      * @return the ordering key of the message
      */
     byte[] getOrderingKey();

     /**
      * Get the topic the message was published to.
      *
      * @return the topic the message was published to
      */
     String getTopicName();

     /**
      * {@link EncryptionContext} contains encryption and compression information in it using which application can
      * decrypt consumed message with encrypted-payload.
      *
      * @return the optiona encryption context
      */
     Optional<EncryptionContext> getEncryptionCtx();

     /**
      * Get message redelivery count, redelivery count maintain in pulsar broker. When client acknowledge message
      * timeout, broker will dispatch message again with message redelivery count in CommandMessage defined.
      *
      * <p>Message redelivery increases monotonically in a broker, when topic switch ownership to a another broker
      * redelivery count will be recalculated.
      *
      * @since 2.3.0
      * @return message redelivery count
      */
     int getRedeliveryCount();

     /**
      * Get schema version of the message.
      * @since 2.4.0
      * @return Schema version of the message if the message is produced with schema otherwise null.
      */
     byte[] getSchemaVersion();

     /**
      * Get the schema associated to the message.
      * Please note that this schema is usually equal to the Schema you passed
      * during the construction of the Consumer or the Reader.
      * But if you are consuming the topic using the GenericObject interface
      * this method will return the schema associated with the message.
      * @return The schema used to decode the payload of message.
      * @see Schema#AUTO_CONSUME()
      */
     default Optional<Schema<?>> getReaderSchema() {
         return Optional.empty();
     }

     /**
      * Check whether the message is replicated from other cluster.
      *
      * @since 2.4.0
      * @return true if the message is replicated from other cluster.
      *         false otherwise.
      */
     boolean isReplicated();

     /**
      * Get name of cluster, from which the message is replicated.
      *
      * @since 2.4.0
      * @return the name of cluster, from which the message is replicated.
      */
     String getReplicatedFrom();

     /**
      * Release a message back to the pool. This is required only if the consumer was created with the option to pool
      * messages, otherwise it will have no effect.
      *
      * @since 2.8.0
      */
     void release();

     /**
      * Check whether the message has a broker publish time
      *
      * @since 2.9.0
      * @return true if the message has a broker publish time, otherwise false.
      */
     boolean hasBrokerPublishTime();

     /**
      * Get broker publish time from broker entry metadata.
      * Note that only if the feature is enabled in the broker then the value is available.
      *
      * @since 2.9.0
      * @return broker publish time from broker entry metadata, or empty if the feature is not enabled in the broker.
      */
     Optional<Long> getBrokerPublishTime();

     /**
      * Check whether the message has a index.
      *
      * @since 2.9.0
      * @return true if the message has a index, otherwise false.
      */
     boolean hasIndex();

     /**
      * Get index from broker entry metadata.
      * Note that only if the feature is enabled in the broker then the value is available.
      *
      * @since 2.9.0
      * @return index from broker entry metadata, or empty if the feature is not enabled in the broker.
      */
     Optional<Long> getIndex();
 }
	/**
	* 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.util.Map;
	import java.util.Optional;
	import org.apache.pulsar.common.api.EncryptionContext;
	import org.apache.pulsar.common.classification.InterfaceAudience;
	import org.apache.pulsar.common.classification.InterfaceStability;

	/**
	* The message abstraction used in Pulsar.
	*/
	@InterfaceAudience.Public
	@InterfaceStability.Stable
	public interface Message<T> {

	/**
	* Return the properties attached to the message.
	*
	* <p>Properties are application defined key/value pairs that will be attached to the message.
	*
	* @return an unmodifiable view of the properties map
	*/
	Map<String, String> getProperties();

	/**
	* Check whether the message has a specific property attached.
	*
	* @param name the name of the property to check
	* @return true if the message has the specified property and false if the properties is not defined
	*/
	boolean hasProperty(String name);

	/**
	* Get the value of a specific property.
	*
	* @param name the name of the property
	* @return the value of the property or null if the property was not defined
	*/
	String getProperty(String name);

	/**
	* Get the raw payload of the message.
	*
	* <p>Even when using the Schema and type-safe API, an application
	* has access to the underlying raw message payload.
	*
	* @return the byte array with the message payload
	*/
	byte[] getData();

	/**
	* Get the uncompressed message payload size in bytes.
	*
	* @return size in bytes.
	*/
	int size();

	/**
	* Get the de-serialized value of the message, according the configured {@link Schema}.
	*
	* @return the deserialized value of the message
	*/
	T getValue();

	/**
	* Get the unique message ID associated with this message.
	*
	* <p>The message id can be used to univocally refer to a message without having the keep
	* the entire payload in memory.
	*
	* <p>Only messages received from the consumer will have a message id assigned.
	*
	* @return the message id null if this message was not received by this client instance
	*/
	MessageId getMessageId();

	/**
	* Get the publish time of this message. The publish time is the timestamp that a client publish the message.
	*
	* @return publish time of this message.
	* @see #getEventTime()
	*/
	long getPublishTime();

	/**
	* Get the event time associated with this message. It is typically set by the applications via
	* {@link MessageBuilder#setEventTime(long)}.
	*
	* <p>If there isn't any event time associated with this event, it will return 0.
	*
	* @see MessageBuilder#setEventTime(long)
	* @since 1.20.0
	* @return the message event time or 0 if event time wasn't set
	*/
	long getEventTime();

	/**
	* Get the sequence id associated with this message. It is typically set by the applications via
	* {@link MessageBuilder#setSequenceId(long)}.
	*
	* @return sequence id associated with this message.
	* @see MessageBuilder#setEventTime(long)
	* @since 1.22.0
	*/
	long getSequenceId();

	/**
	* Get the producer name who produced this message.
	*
	* @return producer name who produced this message, null if producer name is not set.
	* @since 1.22.0
	*/
	String getProducerName();

	/**
	* Check whether the message has a key.
	*
	* @return true if the key was set while creating the message and false if the key was not set
	* while creating the message
	*/
	boolean hasKey();

	/**
	* Get the key of the message.
	*
	* @return the key of the message
	*/
	String getKey();

	/**
	* Check whether the key has been base64 encoded.
	*
	* @return true if the key is base64 encoded, false otherwise
	*/
	boolean hasBase64EncodedKey();

	/**
	* Get bytes in key. If the key has been base64 encoded, it is decoded before being returned.
	* Otherwise, if the key is a plain string, this method returns the UTF_8 encoded bytes of the string.
	* @return the key in byte[] form
	*/
	byte[] getKeyBytes();

	/**
	* Check whether the message has a ordering key.
	*
	* @return true if the ordering key was set while creating the message
	* false if the ordering key was not set while creating the message
	*/
	boolean hasOrderingKey();

	/**
	* Get the ordering key of the message.
	*
	* @return the ordering key of the message
	*/
	byte[] getOrderingKey();

	/**
	* Get the topic the message was published to.
	*
	* @return the topic the message was published to
	*/
	String getTopicName();

	/**
	* {@link EncryptionContext} contains encryption and compression information in it using which application can
	* decrypt consumed message with encrypted-payload.
	*
	* @return the optiona encryption context
	*/
	Optional<EncryptionContext> getEncryptionCtx();

	/**
	* Get message redelivery count, redelivery count maintain in pulsar broker. When client acknowledge message
	* timeout, broker will dispatch message again with message redelivery count in CommandMessage defined.
	*
	* <p>Message redelivery increases monotonically in a broker, when topic switch ownership to a another broker
	* redelivery count will be recalculated.
	*
	* @since 2.3.0
	* @return message redelivery count
	*/
	int getRedeliveryCount();

	/**
	* Get schema version of the message.
	* @since 2.4.0
	* @return Schema version of the message if the message is produced with schema otherwise null.
	*/
	byte[] getSchemaVersion();

	/**
	* Get the schema associated to the message.
	* Please note that this schema is usually equal to the Schema you passed
	* during the construction of the Consumer or the Reader.
	* But if you are consuming the topic using the GenericObject interface
	* this method will return the schema associated with the message.
	* @return The schema used to decode the payload of message.
	* @see Schema#AUTO_CONSUME()
	*/
	default Optional<Schema<?>> getReaderSchema() {
	return Optional.empty();
	}

	/**
	* Check whether the message is replicated from other cluster.
	*
	* @since 2.4.0
	* @return true if the message is replicated from other cluster.
	* false otherwise.
	*/
	boolean isReplicated();

	/**
	* Get name of cluster, from which the message is replicated.
	*
	* @since 2.4.0
	* @return the name of cluster, from which the message is replicated.
	*/
	String getReplicatedFrom();

	/**
	* Release a message back to the pool. This is required only if the consumer was created with the option to pool
	* messages, otherwise it will have no effect.
	*
	* @since 2.8.0
	*/
	void release();

	/**
	* Check whether the message has a broker publish time
	*
	* @since 2.9.0
	* @return true if the message has a broker publish time, otherwise false.
	*/
	boolean hasBrokerPublishTime();

	/**
	* Get broker publish time from broker entry metadata.
	* Note that only if the feature is enabled in the broker then the value is available.
	*
	* @since 2.9.0
	* @return broker publish time from broker entry metadata, or empty if the feature is not enabled in the broker.
	*/
	Optional<Long> getBrokerPublishTime();

	/**
	* Check whether the message has a index.
	*
	* @since 2.9.0
	* @return true if the message has a index, otherwise false.
	*/
	boolean hasIndex();

	/**
	* Get index from broker entry metadata.
	* Note that only if the feature is enabled in the broker then the value is available.
	*
	* @since 2.9.0
	* @return index from broker entry metadata, or empty if the feature is not enabled in the broker.
	*/
	Optional<Long> getIndex();
	}