org.apache.pulsar.client.api.Schema 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 static org.apache.pulsar.client.internal.DefaultImplementation.getBytes;
import java.nio.ByteBuffer;
import java.sql.Time;
import java.sql.Timestamp;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.util.Date;
import java.util.Optional;
import org.apache.pulsar.client.api.schema.GenericRecord;
import org.apache.pulsar.client.api.schema.GenericSchema;
import org.apache.pulsar.client.api.schema.GenericObject;
import org.apache.pulsar.client.api.schema.SchemaDefinition;
import org.apache.pulsar.client.api.schema.SchemaInfoProvider;
import org.apache.pulsar.client.internal.DefaultImplementation;
import org.apache.pulsar.common.classification.InterfaceAudience;
import org.apache.pulsar.common.classification.InterfaceStability;
import org.apache.pulsar.common.schema.KeyValue;
import org.apache.pulsar.common.schema.KeyValueEncodingType;
import org.apache.pulsar.common.schema.SchemaInfo;
import org.apache.pulsar.common.schema.SchemaType;
/**
* Message schema definition.
*/
@InterfaceAudience.Public
@InterfaceStability.Stable
public interface Schema extends Cloneable{
/**
* 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 {@link #decode(byte[])}
* to see if this schema can decode this message or not as a validation mechanism to verify
* the bytes.
*
* @param message the messages to verify
* @throws SchemaSerializationException if it is not a valid message
*/
default void validate(byte[] message) {
decode(message);
}
/**
* Encode an object representing the message content into a byte array.
*
* @param message
* the message object
* @return a byte array with the serialized content
* @throws SchemaSerializationException
* if the serialization fails
*/
byte[] encode(T message);
/**
* 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
* {@link GenericRecord} should support schema versioning.
*
*
If a schema implementation returns false, it should implement {@link #decode(byte[])};
* while a schema implementation returns true, it should implement {@link #decode(byte[], byte[])}
* instead.
*
* @return true if this schema implementation supports schema versioning; otherwise returns false.
*/
default boolean supportSchemaVersioning() {
return false;
}
default void setSchemaInfoProvider(SchemaInfoProvider schemaInfoProvider) {
}
/**
* Decode a byte array into an object using the schema definition and deserializer implementation.
*
* @param bytes
* the byte array to decode
* @return the deserialized object
*/
default T decode(byte[] bytes) {
// use `null` to indicate ignoring schema version
return decode(bytes, null);
}
/**
* Decode a byte array into an object using a given version.
*
* @param bytes
* the byte array to decode
* @param schemaVersion
* the schema version to decode the object. null indicates using latest version.
* @return the deserialized object
*/
default T decode(byte[] bytes, byte[] schemaVersion) {
// ignore version by default (most of the primitive schema implementations ignore schema version)
return decode(bytes);
}
/**
* Decode a ByteBuffer into an object using a given version.
*
* @param data
* the ByteBuffer to decode
* @param schemaVersion
* the schema version to decode the object. null indicates using latest version.
* @return the deserialized object
*/
default T decode(ByteBuffer data, byte[] schemaVersion) {
if (data == null) {
return null;
}
return decode(getBytes(data), schemaVersion);
}
/**
* @return an object that represents the Schema associated metadata
*/
SchemaInfo getSchemaInfo();
/**
* Check if this schema requires fetching schema info to configure the schema.
*
* @return true if the schema requires fetching schema info to configure the schema,
* otherwise false.
*/
default boolean requireFetchingSchemaInfo() {
return false;
}
/**
* Configure the schema to use the provided schema info.
*
* @param topic topic name
* @param componentName component name
* @param schemaInfo schema info
*/
default void configureSchemaInfo(String topic, String componentName,
SchemaInfo schemaInfo) {
// no-op
}
/**
* Duplicates the schema.
*
* @return The duplicated schema.
*/
Schema clone();
/**
* Schema that doesn't perform any encoding on the message payloads. Accepts a byte array and it passes it through.
*/
Schema BYTES = DefaultImplementation.newBytesSchema();
/**
* Return the native schema that is wrapped by Pulsar API.
* For instance with this method you can access the Avro schema
* @return the internal schema or null if not present
*/
default Optional