connect/api/src/main/java/org/apache/kafka/connect/data/Schema.java

/**
 * 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.kafka.connect.data;

import java.util.List;
import java.util.Map;

/**
 * <p>
 *     Definition of an abstract data type. Data types can be primitive types (integer types, floating point types,
 *     boolean, strings, and bytes) or complex types (typed arrays, maps with one key schema and value schema,
 *     and structs that have a fixed set of field names each with an associated value schema). Any type can be specified
 *     as optional, allowing it to be omitted (resulting in null values when it is missing) and can specify a default
 *     value.
 * </p>
 * <p>
 *     All schemas may have some associated metadata: a name, version, and documentation. These are all considered part
 *     of the schema itself and included when comparing schemas. Besides adding important metadata, these fields enable
 *     the specification of logical types that specify additional constraints and semantics (e.g. UNIX timestamps are
 *     just an int64, but the user needs the know about the additional semantics to interpret it properly).
 * </p>
 * <p>
 *     Schemas can be created directly, but in most cases using {@link SchemaBuilder} will be simpler.
 * </p>
 */
public interface Schema {
    /**
     * The type of a schema. These only include the core types; logical types must be determined by checking the schema name.
     */
    enum Type {
        INT8, INT16, INT32, INT64, FLOAT32, FLOAT64, BOOLEAN, STRING, BYTES, ARRAY, MAP, STRUCT;

        private String name;

        Type() {
            this.name = this.name().toLowerCase();
        }

        public String getName() {
            return name;
        }

        public boolean isPrimitive() {
            switch (this) {
                case INT8:
                case INT16:
                case INT32:
                case INT64:
                case FLOAT32:
                case FLOAT64:
                case BOOLEAN:
                case STRING:
                case BYTES:
                    return true;
            }
            return false;
        }
    }


    Schema INT8_SCHEMA = SchemaBuilder.int8().build();
    Schema INT16_SCHEMA = SchemaBuilder.int16().build();
    Schema INT32_SCHEMA = SchemaBuilder.int32().build();
    Schema INT64_SCHEMA = SchemaBuilder.int64().build();
    Schema FLOAT32_SCHEMA = SchemaBuilder.float32().build();
    Schema FLOAT64_SCHEMA = SchemaBuilder.float64().build();
    Schema BOOLEAN_SCHEMA = SchemaBuilder.bool().build();
    Schema STRING_SCHEMA = SchemaBuilder.string().build();
    Schema BYTES_SCHEMA = SchemaBuilder.bytes().build();

    Schema OPTIONAL_INT8_SCHEMA = SchemaBuilder.int8().optional().build();
    Schema OPTIONAL_INT16_SCHEMA = SchemaBuilder.int16().optional().build();
    Schema OPTIONAL_INT32_SCHEMA = SchemaBuilder.int32().optional().build();
    Schema OPTIONAL_INT64_SCHEMA = SchemaBuilder.int64().optional().build();
    Schema OPTIONAL_FLOAT32_SCHEMA = SchemaBuilder.float32().optional().build();
    Schema OPTIONAL_FLOAT64_SCHEMA = SchemaBuilder.float64().optional().build();
    Schema OPTIONAL_BOOLEAN_SCHEMA = SchemaBuilder.bool().optional().build();
    Schema OPTIONAL_STRING_SCHEMA = SchemaBuilder.string().optional().build();
    Schema OPTIONAL_BYTES_SCHEMA = SchemaBuilder.bytes().optional().build();

    /**
     * @return the type of this schema
     */
    Type type();

    /**
     * @return true if this field is optional, false otherwise
     */
    boolean isOptional();

    /**
     * @return the default value for this schema
     */
    Object defaultValue();

    /**
     * @return the name of this schema
     */
    String name();

    /**
     * Get the optional version of the schema. If a version is included, newer versions *must* be larger than older ones.
     * @return the version of this schema
     */
    Integer version();

    /**
     * @return the documentation for this schema
     */
    String doc();

    /**
     * Get a map of schema parameters.
     * @return Map containing parameters for this schema, or null if there are no parameters
     */
    Map<String, String> parameters();

    /**
     * Get the key schema for this map schema. Throws a DataException if this schema is not a map.
     * @return the key schema
     */
    Schema keySchema();

    /**
     * Get the value schema for this map or array schema. Throws a DataException if this schema is not a map or array.
     * @return the value schema
     */
    Schema valueSchema();

    /**
     * Get the list of fields for this Schema. Throws a DataException if this schema is not a struct.
     * @return the list of fields for this Schema
     */
    List<Field> fields();

    /**
     * Get a field for this Schema by name. Throws a DataException if this schema is not a struct.
     * @param fieldName the name of the field to look up
     * @return the Field object for the specified field, or null if there is no field with the given name
     */
    Field field(String fieldName);

    /**
     * Return a concrete instance of the {@link Schema}
     * @return the {@link Schema}
     */
    Schema schema();
}