Package org.apache.pulsar.client.api

Interface Schema<T>

All Superinterfaces:
Cloneable
All Known Subinterfaces:
GenericSchema<T>, KeyValueSchema<K,V>
@Public @Stable public interface Schema<T> extends Cloneable
Message schema definition.

  • Field Details

    • BYTES

      static final Schema<byte[]> BYTES
      Schema that doesn't perform any encoding on the message payloads. Accepts a byte array and it passes it through.

    • BYTEBUFFER

      static final Schema<ByteBuffer> BYTEBUFFER
      ByteBuffer Schema.

    • STRING

      static final Schema<String> STRING
      Schema that can be used to encode/decode messages whose values are String. The payload is encoded with UTF-8.

    • INT8

      static final Schema<Byte> INT8
      INT8 Schema.

    • INT16

      static final Schema<Short> INT16
      INT16 Schema.

    • INT32

      static final Schema<Integer> INT32
      INT32 Schema.

    • INT64

      static final Schema<Long> INT64
      INT64 Schema.

    • BOOL

      static final Schema<Boolean> BOOL
      Boolean Schema.

    • FLOAT

      static final Schema<Float> FLOAT
      Float Schema.

    • DOUBLE

      static final Schema<Double> DOUBLE
      Double Schema.

    • DATE

      static final Schema<Date> DATE
      Date Schema.

    • TIME

      static final Schema<Time> TIME
      Time Schema.

    • TIMESTAMP

      static final Schema<Timestamp> TIMESTAMP
      Timestamp Schema.

    • INSTANT

      static final Schema<Instant> INSTANT
      Instant Schema.

    • LOCAL_DATE

      static final Schema<LocalDate> LOCAL_DATE
      LocalDate Schema.

    • LOCAL_TIME

      static final Schema<LocalTime> LOCAL_TIME
      LocalTime Schema.

    • LOCAL_DATE_TIME

      static final Schema<LocalDateTime> LOCAL_DATE_TIME
      LocalDateTime Schema.

  • Method Details

    • validate

      default void validate(byte[] message)
      Check if the message is a valid object for this schema.

      The implementation can choose what its most efficient approach to validate the schema. If the implementation doesn't provide it, it will attempt to use decode(byte[]) to see if this schema can decode this message or not as a validation mechanism to verify the bytes.

      Parameters:
      message - the messages to verify
      Throws:
      SchemaSerializationException - if it is not a valid message

    • encode

      byte[] encode(T message)
      Encode an object representing the message content into a byte array.
      Parameters:
      message - the message object
      Returns:
      a byte array with the serialized content
      Throws:
      SchemaSerializationException - if the serialization fails

    • supportSchemaVersioning

      default boolean supportSchemaVersioning()
      Returns whether this schema supports versioning.

      Most of the schema implementations don't really support schema versioning, or it just doesn't make any sense to support schema versionings (e.g. primitive schemas). Only schema returns GenericRecord should support schema versioning.

      If a schema implementation returns false, it should implement decode(byte[]); while a schema implementation returns true, it should implement decode(byte[], byte[]) instead.

      Returns:
      true if this schema implementation supports schema versioning; otherwise returns false.

    • setSchemaInfoProvider

      default void setSchemaInfoProvider(SchemaInfoProvider schemaInfoProvider)

    • decode

      default T decode(byte[] bytes)
      Decode a byte array into an object using the schema definition and deserializer implementation.
      Parameters:
      bytes - the byte array to decode
      Returns:
      the deserialized object

    • decode

      default T decode(byte[] bytes, byte[] schemaVersion)
      Decode a byte array into an object using a given version.
      Parameters:
      bytes - the byte array to decode
      schemaVersion - the schema version to decode the object. null indicates using latest version.
      Returns:
      the deserialized object

    • decode

      default T decode(ByteBuffer data)
      Decode a ByteBuffer into an object using a given version.
      Parameters:
      data - the ByteBuffer to decode
      Returns:
      the deserialized object

    • decode

      default T decode(ByteBuffer data, byte[] schemaVersion)
      Decode a ByteBuffer into an object using a given version.
      Parameters:
      data - the ByteBuffer to decode
      schemaVersion - the schema version to decode the object. null indicates using latest version.
      Returns:
      the deserialized object

    • getSchemaInfo

      SchemaInfo getSchemaInfo()
      Returns:
      an object that represents the Schema associated metadata

    • requireFetchingSchemaInfo

      default boolean requireFetchingSchemaInfo()
      Check if this schema requires fetching schema info to configure the schema.
      Returns:
      true if the schema requires fetching schema info to configure the schema, otherwise false.

    • configureSchemaInfo

      default void configureSchemaInfo(String topic, String componentName, SchemaInfo schemaInfo)
      Configure the schema to use the provided schema info.
      Parameters:
      topic - topic name
      componentName - component name
      schemaInfo - schema info

    • clone

      Schema<T> clone()
      Duplicates the schema.
      Returns:
      The duplicated schema.

    • getNativeSchema

      default Optional<Object> getNativeSchema()
      Return the native schema that is wrapped by Pulsar API. For instance with this method you can access the Avro schema
      Returns:
      the internal schema or null if not present

    • PROTOBUF

      static <T extends com.google.protobuf.GeneratedMessageV3> Schema<T> PROTOBUF(Class<T> clazz)
      Create a Protobuf schema type by extracting the fields of the specified class.
      Parameters:
      clazz - the Protobuf generated class to be used to extract the schema
      Returns:
      a Schema instance

    • PROTOBUF

      static <T extends com.google.protobuf.GeneratedMessageV3> Schema<T> PROTOBUF(SchemaDefinition<T> schemaDefinition)
      Create a Protobuf schema type with schema definition.
      Parameters:
      schemaDefinition - schemaDefinition the definition of the schema
      Returns:
      a Schema instance

    • PROTOBUF_NATIVE

      static <T extends com.google.protobuf.GeneratedMessageV3> Schema<T> PROTOBUF_NATIVE(Class<T> clazz)
      Create a Protobuf-Native schema type by extracting the fields of the specified class.
      Parameters:
      clazz - the Protobuf generated class to be used to extract the schema
      Returns:
      a Schema instance

    • PROTOBUF_NATIVE

      static <T extends com.google.protobuf.GeneratedMessageV3> Schema<T> PROTOBUF_NATIVE(SchemaDefinition<T> schemaDefinition)
      Create a Protobuf-Native schema type with schema definition.
      Parameters:
      schemaDefinition - schemaDefinition the definition of the schema
      Returns:
      a Schema instance

    • AVRO

      static <T> Schema<T> AVRO(Class<T> pojo)
      Create a Avro schema type by default configuration of the class.
      Parameters:
      pojo - the POJO class to be used to extract the Avro schema
      Returns:
      a Schema instance

    • AVRO

      static <T> Schema<T> AVRO(SchemaDefinition<T> schemaDefinition)
      Create a Avro schema type with schema definition.
      Parameters:
      schemaDefinition - the definition of the schema
      Returns:
      a Schema instance

    • JSON

      static <T> Schema<T> JSON(Class<T> pojo)
      Create a JSON schema type by extracting the fields of the specified class.
      Parameters:
      pojo - the POJO class to be used to extract the JSON schema
      Returns:
      a Schema instance

    • JSON

      static <T> Schema<T> JSON(SchemaDefinition schemaDefinition)
      Create a JSON schema type with schema definition.
      Parameters:
      schemaDefinition - the definition of the schema
      Returns:
      a Schema instance

    • KeyValue

      static <K, V> Schema<KeyValue<K,V>> KeyValue(Class<K> key, Class<V> value, SchemaType type)
      Key Value Schema using passed in schema type, support JSON and AVRO currently.

    • KV_BYTES

      static Schema<KeyValue<byte[],byte[]>> KV_BYTES()
      Schema that can be used to encode/decode KeyValue.

    • KeyValue

      static <K, V> Schema<KeyValue<K,V>> KeyValue(Class<K> key, Class<V> value)
      Key Value Schema whose underneath key and value schemas are JSONSchema.

    • KeyValue

      static <K, V> Schema<KeyValue<K,V>> KeyValue(Schema<K> key, Schema<V> value)
      Key Value Schema using passed in key and value schemas.

    • KeyValue

      static <K, V> Schema<KeyValue<K,V>> KeyValue(Schema<K> key, Schema<V> value, KeyValueEncodingType keyValueEncodingType)
      Key Value Schema using passed in key, value and encoding type schemas.

    • AUTO

      @Deprecated static Schema<GenericRecord> AUTO()
      Deprecated.

    • AUTO_CONSUME

      static Schema<GenericRecord> AUTO_CONSUME()
      Create a schema instance that automatically deserialize messages based on the current topic schema.

      The messages values are deserialized into a GenericRecord object, that extends the GenericObject interface.

      Returns:
      the auto schema instance

    • AUTO_PRODUCE_BYTES

      static Schema<byte[]> AUTO_PRODUCE_BYTES()
      Create a schema instance that accepts a serialized payload and validates it against the topic schema.

      Currently this is only supported with Avro and JSON schema types.

      This method can be used when publishing a raw JSON payload, for which the format is known and a POJO class is not available.

      Returns:
      the auto schema instance

    • AUTO_PRODUCE_BYTES

      static Schema<byte[]> AUTO_PRODUCE_BYTES(Schema<?> schema)
      Create a schema instance that accepts a serialized payload and validates it against the schema specified.
      Returns:
      the auto schema instance
      Since:
      2.5.0
      See Also:

    • NATIVE_AVRO

      static Schema<byte[]> NATIVE_AVRO(Object schema)
      Create a schema instance that accepts a serialized Avro payload without validating it against the schema specified. It can be useful when migrating data from existing event or message stores.
      Returns:
      the auto schema instance
      Since:
      2.9.0

    • getSchema

      static Schema<?> getSchema(SchemaInfo schemaInfo)

    • generic

      static GenericSchema<GenericRecord> generic(SchemaInfo schemaInfo)
      Returns a generic schema of existing schema info.

      Only supports AVRO and JSON.

      Parameters:
      schemaInfo - schema info
      Returns:
      a generic schema instance