org.apache.avro

## Class Schema

- java.lang.Object
- - org.apache.avro.JsonProperties
  - - org.apache.avro.Schema

- All Implemented Interfaces:
    Serializable

      public abstract class Schema
      extends JsonProperties
      implements Serializable

  An abstract data type.

  A schema may be one of:

  - A record, mapping field names to field value data;
  - An enum, containing one of a small set of symbols;
  - An array of values, all of the same schema;
  - A map, containing string/value pairs, of a declared schema;
  - A union of other schemas;
  - A fixed sized binary object;
  - A unicode string;
  - A sequence of bytes;
  - A 32-bit signed int;
  - A 64-bit signed long;
  - A 32-bit IEEE single-float; or
  - A 64-bit IEEE double-float; or
  - A boolean; or
  - null.
  A schema can be constructed using one of its static `createXXX` methods, or more conveniently using `SchemaBuilder`. The schema objects are logically immutable. There are only two mutating methods - `setFields(List)` and `addProp(String, String)`. The following restrictions apply on these two methods.
  - `setFields(List)`, can be called at most once. This method exists in order to enable clients to build recursive schemas.
  - `addProp(String, String)` can be called with property names that are not present already. It is not possible to change or delete an existing property.
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Schema.Field` A field within a record.
    `static class` | `Schema.Parser` A parser for JSON-format schemas.
    `static class` | `Schema.SeenPair` Useful as key of `Map`s when traversing two schemas at the same time and need to watch for recursion.
    `static class` | `Schema.Type` The type of a schema.

    - ### Nested classes/interfaces inherited from class org.apache.avro.JsonProperties

      `JsonProperties.Null`

  - ### Field Summary

    - ### Fields inherited from class org.apache.avro.JsonProperties

      `NULL_VALUE`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAlias(String alias)` If this is a record, enum or fixed, add an alias.
    `void` | `addAlias(String alias, String space)` If this is a record, enum or fixed, add an alias.
    `void` | `addProp(String name, Object value)`
    `void` | `addProp(String name, String value)` Adds a property with the given name `name` and value `value`.
    `static Schema` | `applyAliases(Schema writer, Schema reader)` Rewrite a writer's schema using the aliases from a reader's schema.
    `static Schema` | `create(Schema.Type type)` Create a schema for a primitive type.
    `static Schema` | `createArray(Schema elementType)` Create an array schema.
    `static Schema` | `createEnum(String name, String doc, String namespace, List<String> values)` Create an enum schema.
    `static Schema` | `createEnum(String name, String doc, String namespace, List<String> values, String enumDefault)` Create an enum schema.
    `static Schema` | `createFixed(String name, String doc, String space, int size)` Create a fixed schema.
    `static Schema` | `createMap(Schema valueType)` Create a map schema.
    `static Schema` | `createRecord(List<Schema.Field> fields)` Deprecated. This method allows to create Schema objects that cannot be parsed by `Schema.Parser.parse(String)`. It will be removed in a future version of Avro. Better use i`createRecord(String, String, String, boolean, List)` to produce a fully qualified Schema.
    `static Schema` | `createRecord(String name, String doc, String namespace, boolean isError)` Create a named record schema.
    `static Schema` | `createRecord(String name, String doc, String namespace, boolean isError, List<Schema.Field> fields)` Create a named record schema with fields already set.
    `static Schema` | `createUnion(List<Schema> types)` Create a union schema.
    `static Schema` | `createUnion(Schema... types)` Create a union schema.
    `boolean` | `equals(Object o)`
    `Set<String>` | `getAliases()` If this is a record, enum or fixed, return its aliases, if any.
    `String` | `getDoc()` If this is a record, enum, or fixed, returns its docstring, if available.
    `Schema` | `getElementType()` If this is an array, returns its element type.
    `String` | `getEnumDefault()` If this is an enum, return its default value.
    `int` | `getEnumOrdinal(String symbol)` If this is an enum, return a symbol's ordinal value.
    `List<String>` | `getEnumSymbols()` If this is an enum, return its symbols.
    `Schema.Field` | `getField(String fieldname)` If this is a record, returns the Field with the given name `fieldName`.
    `List<Schema.Field>` | `getFields()` If this is a record, returns the fields in it.
    `int` | `getFixedSize()` If this is fixed, returns its size.
    `String` | `getFullName()` If this is a record, enum or fixed, returns its namespace-qualified name, otherwise returns the name of the primitive type.
    `Integer` | `getIndexNamed(String name)` If this is a union, return the branch with the provided full name.
    `LogicalType` | `getLogicalType()`
    `String` | `getName()` If this is a record, enum or fixed, returns its name, otherwise the name of the primitive type.
    `String` | `getNamespace()` If this is a record, enum or fixed, returns its namespace, if any.
    `Schema.Type` | `getType()` Return the type of this schema.
    `List<Schema>` | `getTypes()` If this is a union, returns its types.
    `Schema` | `getValueType()` If this is a map, returns its value type.
    `boolean` | `hasEnumSymbol(String symbol)` If this is an enum, returns true if it contains given symbol.
    `boolean` | `hasFields()` If this is a record, returns whether the fields have been set.
    `int` | `hashCode()`
    `boolean` | `isError()` Returns true if this record is an error type.
    `boolean` | `isNullable()` Returns true if this record is an union type containing null.
    `boolean` | `isUnion()` Returns true if this record is an union type.
    `static Schema` | `parse(File file)` Deprecated. use `Schema.Parser` instead.
    `static Schema` | `parse(InputStream in)` Deprecated. use `Schema.Parser` instead.
    `static Schema` | `parse(String jsonSchema)` Deprecated. use `Schema.Parser` instead.
    `static Schema` | `parse(String jsonSchema, boolean validate)` Deprecated. use `Schema.Parser` instead.
    `static Object` | `parseJsonToObject(String s)` Parses the specified json string to an object.
    `void` | `setFields(List<Schema.Field> fields)` If this is a record, set its fields.
    `String` | `toString()` Render this as JSON.
    `String` | `toString(boolean pretty)` Render this as JSON.
    `String` | `toString(Collection<Schema> referencedSchemas, boolean pretty)` Deprecated.
    `protected Object` | `writeReplace()`

    - ### Methods inherited from class org.apache.avro.JsonProperties

      `addAllProps, getObjectProp, getObjectProps, getProp, hasProps, putAll`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### writeReplace

          protected Object writeReplace()

    - #### create

          public static Schema create(Schema.Type type)

      Create a schema for a primitive type.

    - #### addProp

          public void addProp(String name,
                              String value)

      Description copied from class: `JsonProperties`
      Adds a property with the given name `name` and value `value`. Neither `name` nor `value` can be `null`. It is illegal to add a property if another with the same name but different value already exists in this schema.
      Overrides:
        `addProp` in class `JsonProperties`
      Parameters:
        `name` - The name of the property to add
        `value` - The value for the property to add

    - #### addProp

          public void addProp(String name,
                              Object value)

      Overrides:
        `addProp` in class `JsonProperties`

    - #### getLogicalType

          public LogicalType getLogicalType()

    - #### createRecord

          @Deprecated
          public static Schema createRecord(List<Schema.Field> fields)

      Deprecated. This method allows to create Schema objects that cannot be parsed by `Schema.Parser.parse(String)`. It will be removed in a future version of Avro. Better use i`createRecord(String, String, String, boolean, List)` to produce a fully qualified Schema.
      Create an anonymous record schema.

    - #### createRecord

          public static Schema createRecord(String name,
                                            String doc,
                                            String namespace,
                                            boolean isError)

      Create a named record schema.

    - #### createRecord

          public static Schema createRecord(String name,
                                            String doc,
                                            String namespace,
                                            boolean isError,
                                            List<Schema.Field> fields)

      Create a named record schema with fields already set.

    - #### createEnum

          public static Schema createEnum(String name,
                                          String doc,
                                          String namespace,
                                          List<String> values)

      Create an enum schema.

    - #### createEnum

          public static Schema createEnum(String name,
                                          String doc,
                                          String namespace,
                                          List<String> values,
                                          String enumDefault)

      Create an enum schema.

    - #### createArray

          public static Schema createArray(Schema elementType)

      Create an array schema.

    - #### createMap

          public static Schema createMap(Schema valueType)

      Create a map schema.

    - #### createUnion

          public static Schema createUnion(List<Schema> types)

      Create a union schema.

    - #### createUnion

          public static Schema createUnion(Schema... types)

      Create a union schema.

    - #### createFixed

          public static Schema createFixed(String name,
                                           String doc,
                                           String space,
                                           int size)

      Create a fixed schema.

    - #### getType

          public Schema.Type getType()

      Return the type of this schema.

    - #### getField

          public Schema.Field getField(String fieldname)

      If this is a record, returns the Field with the given name `fieldName`. If there is no field by that name, a `null` is returned.

    - #### getFields

          public List<Schema.Field> getFields()

      If this is a record, returns the fields in it. The returned list is in the order of their positions.

    - #### hasFields

          public boolean hasFields()

      If this is a record, returns whether the fields have been set.

    - #### setFields

          public void setFields(List<Schema.Field> fields)

      If this is a record, set its fields. The fields can be set only once in a schema.

    - #### getEnumSymbols

          public List<String> getEnumSymbols()

      If this is an enum, return its symbols.

    - #### getEnumDefault

          public String getEnumDefault()

      If this is an enum, return its default value.

    - #### getEnumOrdinal

          public int getEnumOrdinal(String symbol)

      If this is an enum, return a symbol's ordinal value.

    - #### hasEnumSymbol

          public boolean hasEnumSymbol(String symbol)

      If this is an enum, returns true if it contains given symbol.

    - #### getName

          public String getName()

      If this is a record, enum or fixed, returns its name, otherwise the name of the primitive type.

    - #### getDoc

          public String getDoc()

      If this is a record, enum, or fixed, returns its docstring, if available. Otherwise, returns null.

    - #### getNamespace

          public String getNamespace()

      If this is a record, enum or fixed, returns its namespace, if any.

    - #### getFullName

          public String getFullName()

      If this is a record, enum or fixed, returns its namespace-qualified name, otherwise returns the name of the primitive type.

    - #### addAlias

          public void addAlias(String alias)

      If this is a record, enum or fixed, add an alias.

    - #### addAlias

          public void addAlias(String alias,
                               String space)

      If this is a record, enum or fixed, add an alias.

    - #### getAliases

          public Set<String> getAliases()

      If this is a record, enum or fixed, return its aliases, if any.

    - #### isError

          public boolean isError()

      Returns true if this record is an error type.

    - #### getElementType

          public Schema getElementType()

      If this is an array, returns its element type.

    - #### getValueType

          public Schema getValueType()

      If this is a map, returns its value type.

    - #### getTypes

          public List<Schema> getTypes()

      If this is a union, returns its types.

    - #### getIndexNamed

          public Integer getIndexNamed(String name)

      If this is a union, return the branch with the provided full name.

    - #### getFixedSize

          public int getFixedSize()

      If this is fixed, returns its size.

    - #### toString

          public String toString()

      Render this as JSON.
      Overrides:
        `toString` in class `Object`

    - #### toString

          public String toString(boolean pretty)

      Render this as JSON.
      Parameters:
        `pretty` - if true, pretty-print JSON.

    - #### toString

          @Deprecated
          public String toString(Collection<Schema> referencedSchemas,
                                             boolean pretty)

      Deprecated.
      Render this as JSON, but without inlining the referenced schemas.
      Parameters:
        `referencedSchemas` - referenced schemas
        `pretty` - if true, pretty-print JSON.

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### isUnion

          public boolean isUnion()

      Returns true if this record is an union type.

    - #### isNullable

          public boolean isNullable()

      Returns true if this record is an union type containing null.

    - #### parse

          @Deprecated
          public static Schema parse(File file)
                                          throws IOException

      Deprecated. use `Schema.Parser` instead.
      Constructs a Schema object from JSON schema file `file`. The contents of `file` is expected to be in UTF-8 format.
      Parameters:
        `file` - The file to read the schema from.
      Returns:
        The freshly built Schema.
      Throws:
        `IOException` - if there was trouble reading the contents or they are invalid

    - #### parse

          @Deprecated
          public static Schema parse(InputStream in)
                                          throws IOException

      Deprecated. use `Schema.Parser` instead.
      Constructs a Schema object from JSON schema stream `in`. The contents of `in` is expected to be in UTF-8 format.
      Parameters:
        `in` - The input stream to read the schema from.
      Returns:
        The freshly built Schema.
      Throws:
        `IOException` - if there was trouble reading the contents or they are invalid

    - #### parse

          @Deprecated
          public static Schema parse(String jsonSchema)

      Deprecated. use `Schema.Parser` instead.
      Construct a schema from JSON text.

    - #### parse

          @Deprecated
          public static Schema parse(String jsonSchema,
                                                 boolean validate)

      Deprecated. use `Schema.Parser` instead.
      Construct a schema from JSON text.
      Parameters:
        `validate` - true if names should be validated, false if not.

    - #### parseJsonToObject

          public static Object parseJsonToObject(String s)

      Parses the specified json string to an object.

    - #### applyAliases

          public static Schema applyAliases(Schema writer,
                                            Schema reader)

      Rewrite a writer's schema using the aliases from a reader's schema. This permits reading records, enums and fixed schemas whose names have changed, and records whose field names have changed. The returned schema always contains the same data elements in the same order, but with possibly different names.

Copyright © 2009–2024 The Apache Software Foundation. All rights reserved.