com.streambase.sb

## Class Schema

- java.lang.Object
- - com.streambase.sb.Schema

- All Implemented Interfaces:
    Serializable, Iterable<Schema.Field>

      public class Schema
      extends Object
      implements Serializable, Iterable<Schema.Field>

  Represents a StreamBase schema as a list of `Schema.Field`s, and should be used to create `Tuple` objects. Schemas are immutable: once constructed they may not be changed.

  API warning: all constructors that take a `String` name are to be provided only with a `null` name when used by clients, custom operators and adapters. Use of non-null schema names in these contexts may yield unpredictable behavior during Studio authoring and typechecking when a Named Schema exists with the same name.

  Future versions of StreamBase may deprecate the `name` argument.

  Serializations of instances of this class that are created (e.g., by using `ObjectOutputStream`) in one version of StreamBase in general will not be deserializable in any other version of StreamBase.

  Since:
    7.1 Schemas are allowed to have no fields. Schemas are `Iterable` to access its (top-level only) fields., 7.2 Schemas within the server can be derived from other schemas. Schemas are considered equal if their fields, in order, are equal and their names are equal.
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Schema.Field` Information (name, type, and optionally size) about a field in a Schema.
    `(package private) static interface` | `Schema.TupleClassInfo` A placeholder interface to add a bit of type safety to the get/setTupleClassInfo methods.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `ALLOW_TUPLE_FIELD_SAME_NAME`
    `static Schema` | `EMPTY_SCHEMA` An empty schema
    `static int` | `NO_SUCH_FIELD` Used to indicate that a Field does not exist

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Schema(Element element)` Construct a Schema from an XMLElement
    `Schema(Schema baseSchema)` Construct a Schema from another schema
    `Schema(String xmlSchema)` Construct a Schema out of XML represented as a String
    `Schema(String name, List<Schema.Field> fields)` Create a new schema from a list of `Schema.Field`
    `Schema(String name, Schema.Field... fields)` Construct a Schema out of a list of `Schema.Field`
    `Schema(String name, Schema baseSchema)` Construct a Schema with a new name from another schema
    `Schema(String name, String description, Schema.Field... fields)` Construct a Schema out of a list of `Schema.Field`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Schema.Field` | `createField(DataType type, String name)` Creates a new Field of the given DataType, with the given name.
    `static Schema.Field` | `createFunctionField(String fieldName, Schema argumentSchema, CompleteDataType returnType)` Creates a new Field of type FUNCTION, with the given name, argument list and return type.
    `static Schema.Field` | `createListField(String name, CompleteDataType elementType)` Creates a new Field of type LIST, with the given name and given element type
    `Tuple` | `createTuple()` Create a Tuple with this schema.
    `Tuple` | `createTuple(List<String> fieldValues, int offset, int length)` Create a Tuple with this schema from the supplied collection of strings
    `Tuple` | `createTuple(List<String> fieldValues, int offset, int length, String nullString)` Create a Tuple with this schema from the supplied collection of strings
    `Tuple` | `createTuple(String... fieldValues)` Create a Tuple with this schema from the supplied collection of strings
    `Tuple` | `createTuple(String[] fieldValues, int offset, int length)` Create a Tuple with this schema from the supplied collection of strings
    `Tuple` | `createTuple(String[] fieldValues, int offset, int length, String nullString)` Create a Tuple with this schema from the supplied collection of strings
    `static Schema.Field` | `createTupleField(String name, Schema schema)` Creates a new Field of type TUPLE, with the given name and given schema
    `boolean` | `equals(Object obj)` Return true if the supplied schema is the same as this schema.
    `boolean` | `equalsNoCapture(Schema scm)`
    `List<Schema.Field>` | `fields()` Return a List of the Fields in this Schema
    `int` | `getApproximateSize()` Calculates an estimate for the size of a tuple with this schema, including the header and null mask.
    `String` | `getDescription()` Returns the description currently set for this Schema.
    `static Schema` | `getErrorSchema()`
    `Schema.Field` | `getField(int fieldIndex)` Return a Field object at the given index within the schema
    `Schema.Field` | `getField(String fieldPathName)` Return a Field object with the given field pathname in or under this schema.
    `int` | `getFieldCount()` Return the number of Fields within the Schema.
    `int` | `getFieldIndex(CharSequence fieldName)` Return the index within the Schema of the Field with the given name
    `int` | `getFieldIndex(String fieldName)` Return the index within the Schema of the Field with the given name
    `Schema.Field[]` | `getFields()` Return an array of Field objects corresponding to the fields in the schema.
    `DataType[]` | `getFieldTypes()` A utility function to speed up multiple accesses to field types of a schema in contexts where multiple tuples are processed; the function should be called outside of for loops processing tuples and their fields
    `byte[]` | `getHash()` Return the hash for this schema generated by the server.
    `Schema` | `getLocallyDefinedFields()`
    `String` | `getName()` Return the name of the Schema or null at runtime.
    `List<Schema>` | `getParentSchemas()`
    `boolean` | `hasField(CharSequence fieldPathName)` Return true if the Schema has a field with the given name, or false if not.
    `int` | `hashCode()`
    `boolean` | `isSubsetOf(Schema schema)` Returns true if this schema's fields are a subset of the supplied schema's fields Does not recursively test nested schemas for subsetness.
    `boolean` | `isSupersetOf(Schema schema)` Returns true if this schema's fields are a superset of the supplied schema's fields Does not recursively test nested schemas for subsetness.
    `Iterator<Schema.Field>` | `iterator()`
    `boolean` | `sameFieldsAs(Schema other)` Returns true if this schema has the same field types and names in the same order as another Schema.
    `boolean` | `sameFieldTypes(Schema other)` Returns true if this schema has the same field types in the same order as another Schema
    `void` | `setDescription(String description)` Sets this schema's description.
    `(package private) void` | `setTupleClassInfo(Class<? extends Tuple> tupleClass, Schema.TupleClassInfo info)` Set class-specific info about this schema.
    `Element` | `toElement(Document document)` Create an XML document representation of this Schema
    `Element` | `toElement(Document document, boolean addUUID)` Create an XML document representation of this Schema
    `String` | `toHumanString()` Return a description of the Schema in using a SSQL style format
    `String` | `toSsqlStyleString()` Deprecated.
    `String` | `toString()` Return the name of the schema
    `String` | `toStringWithFields()` Deprecated.

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

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

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Field Detail

    - #### ALLOW_TUPLE_FIELD_SAME_NAME

          public static final boolean ALLOW_TUPLE_FIELD_SAME_NAME

    - #### EMPTY_SCHEMA

          public static final Schema EMPTY_SCHEMA

      An empty schema

    - #### NO_SUCH_FIELD

          public static final int NO_SUCH_FIELD

      Used to indicate that a Field does not exist
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Schema

          public Schema(String name,
                        List<Schema.Field> fields)

      Create a new schema from a list of `Schema.Field`
      Parameters:
        `name` - the name of this new schema, generally null. See the class-level documentation for `Schema` for details.
        `fields` - an ordered list of 0 or more fields. Must not be null.
      Throws:
        `IllegalArgumentException` - if the schema name is invalid

    - #### Schema

          public Schema(Element element)
                 throws XmlInterpretationException

      Construct a Schema from an XMLElement
      Parameters:
        `element` - The Element to start from
      Throws:
        `XmlInterpretationException` - thrown when unable to create a Schema object from the XML Element
        `IllegalArgumentException` - if the schema name is invalid

    - #### Schema

          public Schema(String xmlSchema)
                 throws StreamBaseException

      Construct a Schema out of XML represented as a String
      Parameters:
        `xmlSchema` - The String representation of the string in XML
      Throws:
        `StreamBaseException` - thrown when unable to parse `xmlSchema` as an XML document
        `XmlInterpretationException` - thrown when unable to create a Schema object from the XML Element
        `IllegalArgumentException` - if the schema name is invalid

    - #### Schema

          public Schema(String name,
                        Schema.Field... fields)

      Construct a Schema out of a list of `Schema.Field`
      Parameters:
        `name` - the name of this new schema, generally null. See the class-level documentation for `Schema` for details.
        `fields` - an array of 0 or more fields. Must not be null.
      Throws:
        `IllegalArgumentException` - if the schema name is invalid

    - #### Schema

          public Schema(String name,
                        String description,
                        Schema.Field... fields)

      Construct a Schema out of a list of `Schema.Field`
      Parameters:
        `name` - the name of this new schema, generally null. See the class-level documentation for `Schema` for details.
        `description` - optionally, the description that this schema has
        `fields` - an array of 0 or more fields. Must not be null.
      Throws:
        `IllegalArgumentException` - if the schema name is invalid
      Since:
        7.2.5

    - #### Schema

          public Schema(String name,
                        Schema baseSchema)

      Construct a Schema with a new name from another schema
      Parameters:
        `name` - the name of this new schema, generally null. See the class-level documentation for `Schema` for details.
        `baseSchema` - the base schema
      Throws:
        `IllegalArgumentException` - if the schema name is invalid

    - #### Schema

          public Schema(Schema baseSchema)

      Construct a Schema from another schema
      Parameters:
        `baseSchema` - the base schema

  - ### Method Detail

    - #### getErrorSchema

          public static final Schema getErrorSchema()

      Returns:
        the schema of the error tuple

    - #### createField

          public static Schema.Field createField(DataType type,
                                                 String name)

      Creates a new Field of the given DataType, with the given name. Valid only for DataTypes that do not require additional information to instantiate.
      Parameters:
        `type` - the DataType for the new field
        `name` - the new field's name
      Returns:
        a Schema.Field of the given DataType, using name as the field name
      See Also:
        `createField(DataType, String, int)`

    - #### createListField

          public static Schema.Field createListField(String name,
                                                     CompleteDataType elementType)

      Creates a new Field of type LIST, with the given name and given element type
      Parameters:
        `name` - the new field's name
        `elementType` - the list's element type
      Returns:
        a Schema.Field representing the LIST field
      Since:
        6.3

    - #### createTupleField

          public static Schema.Field createTupleField(String name,
                                                      Schema schema)

      Creates a new Field of type TUPLE, with the given name and given schema
      Parameters:
        `name` - the new field's name
        `schema` - the tuple's schema
      Returns:
        a Schema.Field representing the TUPLE field
      Since:
        6.3

    - #### createFunctionField

          public static Schema.Field createFunctionField(String fieldName,
                                                         Schema argumentSchema,
                                                         CompleteDataType returnType)

      Creates a new Field of type FUNCTION, with the given name, argument list and return type.
      Parameters:
        `fieldName` - the new field's name
        `argumentSchema` - the function's arguments
        `returnType` - the function's return type
      Returns:
        a Schema.Field representing the FUNCTION field
      Since:
        7.4

    - #### getField

          public Schema.Field getField(int fieldIndex)

      Return a Field object at the given index within the schema
      Parameters:
        `fieldIndex` - The index of the Field
      Returns:
        The Field

    - #### getField

          public Schema.Field getField(String fieldPathName)
                                throws TupleException

      Return a Field object with the given field pathname in or under this schema. A field pathname consists of one or more simple field names separated by "."s. A simple field name is the name of a field in a schema. A field path name allows one to "drill through" multiply nested schemas (i.e., schemas within schemas due to the presence of fields of type Tuple).
      Parameters:
        `fieldPathName` - The path name of the Field to search for. Path name segments with exotic identifiers are spelled with an initial #" and a final ", with all internal quotes and backslashes escaped with backslashes similar to SSQL string literals.
      Returns:
        The Field
      Throws:
        `TupleException` - thrown when the Field cannot be found

    - #### fields

          public List<Schema.Field> fields()

      Return a List of the Fields in this Schema
      Returns:
        List of the Fields in this Schema

    - #### getFields

          public Schema.Field[] getFields()

      Return an array of Field objects corresponding to the fields in the schema.
      Returns:
        the array of fields

    - #### getFieldTypes

          public DataType[] getFieldTypes()

      A utility function to speed up multiple accesses to field types of a schema in contexts where multiple tuples are processed; the function should be called outside of for loops processing tuples and their fields
      Returns:
        an array of DataTypes corresponding to Schema fields

    - #### getFieldCount

          public int getFieldCount()

      Return the number of Fields within the Schema.
      Returns:
        The number of Fields within the Schema

    - #### getFieldIndex

          public int getFieldIndex(CharSequence fieldName)

      Return the index within the Schema of the Field with the given name
      Parameters:
        `fieldName` - The name (note: not path name) of the Field to search for
      Returns:
        The index of the Field with the given name, or NO_SUCH_FIELD if this schema contains no field named fieldName
      Since:
        6.5

    - #### getFieldIndex

          public int getFieldIndex(String fieldName)

      Return the index within the Schema of the Field with the given name
      Parameters:
        `fieldName` - The name (note: not path name) of the Field to search for
      Returns:
        The index of the Field with the given name, or NO_SUCH_FIELD if this schema contains no field named fieldName

    - #### hasField

          public boolean hasField(CharSequence fieldPathName)

      Return true if the Schema has a field with the given name, or false if not.
      Parameters:
        `fieldPathName` - The path name of the Field to search for
      Returns:
        whether the Schema has a field with the given name.
      Since:
        6.5

    - #### sameFieldTypes

          public boolean sameFieldTypes(Schema other)

      Returns true if this schema has the same field types in the same order as another Schema
      Parameters:
        `other` - the schema to compare to
      Returns:
        whether other "matches" this one

    - #### sameFieldsAs

          public boolean sameFieldsAs(Schema other)

      Returns true if this schema has the same field types and names in the same order as another Schema.
      Parameters:
        `other` - the schema to compare to
      Returns:
        whether other "matches" this one

    - #### getName

          public String getName()

      Return the name of the Schema or null at runtime. The name only has meaning during application development. The runtime totally ignores the name.
      Returns:
        The name of the Schema or null at runtime

    - #### getHash

          public byte[] getHash()

      Return the hash for this schema generated by the server.
      Returns:
        Hash for the schema

    - #### setTupleClassInfo

          void setTupleClassInfo(Class<? extends Tuple> tupleClass,
                                 Schema.TupleClassInfo info)

      Set class-specific info about this schema.
      Parameters:
        `tupleClass` -
        `info` -

    - #### toString

          public String toString()

      Return the name of the schema
      Overrides:
        `toString` in class `Object`
      Returns:
        the name of the schema

    - #### toStringWithFields

          public String toStringWithFields()

      Deprecated.
      Return a String representation of this Schema
      Returns:
        String representation of this Schema
      See Also:
        `Schema.toHumanString()`

    - #### toHumanString

          public String toHumanString()

      Return a description of the Schema in using a SSQL style format
      Returns:
        a description of the Schema in using a SSQL style format

    - #### toSsqlStyleString

          public String toSsqlStyleString()

      Deprecated.
      Return a description of the Schema in using a SSQL style format
      Returns:
        a description of the Schema in using a SSQL style format
      See Also:
        `Schema.toHumanString()`

    - #### toElement

          public Element toElement(Document document)

      Create an XML document representation of this Schema
      Parameters:
        `document` - The Document that the XML Document will belong to.
      Returns:
        an XML document representation of this schema

    - #### toElement

          public Element toElement(Document document,
                                   boolean addUUID)

      Create an XML document representation of this Schema
      Parameters:
        `document` - The Document that the XML Document will belong to.
        `addUUID` - add the UUID to the output xml
      Returns:
        an XML document representation of this schema

    - #### createTuple

          public Tuple createTuple()

      Create a Tuple with this schema.
      Returns:
        a new tuple

    - #### createTuple

          public Tuple createTuple(String... fieldValues)
                            throws TupleException

      Create a Tuple with this schema from the supplied collection of strings
      Parameters:
        `fieldValues` - the field values to set the tuple to
      Returns:
        a new tuple
      Throws:
        `TupleException` - if the number of fields is incorrect, or a conversion error occurs
      See Also:
        `for more info`

    - #### createTuple

          public Tuple createTuple(String[] fieldValues,
                                   int offset,
                                   int length)
                            throws TupleException

      Create a Tuple with this schema from the supplied collection of strings

      For a field of type Tuple the associated string must be a comma-separated list of values appropriate to the schema of that field. In general, the string follows standard "command-separated value" (CSV) rules which can come into play with more deeply nested tuple fields that require quoting.

      See RFC 4180 for info on CSV format

      Parameters:
        `fieldValues` - the field values to set the tuple to
        `offset` - offset into fieldValues list
        `length` - number of values to copy into tuple must be same as number of fields in this Schema
      Throws:
        `TupleException` - if the number of fields is incorrect, or a conversion error occurs

    - #### createTuple

          public Tuple createTuple(String[] fieldValues,
                                   int offset,
                                   int length,
                                   String nullString)
                            throws TupleException

      Create a Tuple with this schema from the supplied collection of strings
      Parameters:
        `fieldValues` - the field values to set the tuple to
        `offset` - offset into fieldValues list
        `length` - number of values to copy into tuple must be same as number of fields in this Schema
        `nullString` - a string to consider as null if it is encountered as a value; use null to never consider field values to be null
      Throws:
        `TupleException` - if the number of fields is incorrect, or a conversion error occurs
      See Also:
        `for more info`

    - #### createTuple

          public Tuple createTuple(List<String> fieldValues,
                                   int offset,
                                   int length)
                            throws TupleException

      Create a Tuple with this schema from the supplied collection of strings
      Parameters:
        `fieldValues` - the field values to set the tuple to
        `offset` - offset into fieldValues list
        `length` - number of values to copy into tuple must be same as number of fields in this Schema
      Returns:
        a new tuple
      Throws:
        `TupleException` - if the number of fields is incorrect, or a conversion error occurs
      See Also:
        `for more info`

    - #### createTuple

          public Tuple createTuple(List<String> fieldValues,
                                   int offset,
                                   int length,
                                   String nullString)
                            throws TupleException

      Create a Tuple with this schema from the supplied collection of strings
      Parameters:
        `fieldValues` - the field values to set the tuple to
        `offset` - offset into fieldValues list
        `length` - number of values to copy into tuple must be same as number of fields in this Schema
        `nullString` - a string to consider as null if it is encountered as a value; use null to never consider field values to be null
      Returns:
        a new tuple
      Throws:
        `TupleException` - if the number of fields is incorrect, or a conversion error occurs
      See Also:
        `for more info`

    - #### equalsNoCapture

          public boolean equalsNoCapture(Schema scm)

    - #### equals

          public boolean equals(Object obj)

      Return true if the supplied schema is the same as this schema. The two schemas are the same if they are structurally the same (all the fields have the same types and names and are in the same order).
      Overrides:
        `equals` in class `Object`
      Parameters:
        `obj` - the schema to compare this schema to
      Returns:
        true if the two schemas are the same

    - #### isSubsetOf

          public boolean isSubsetOf(Schema schema)

      Returns true if this schema's fields are a subset of the supplied schema's fields Does not recursively test nested schemas for subsetness.
      Parameters:
        `schema` - the schema against which to compare
      Returns:
        true if this schema's fields are a subset of the supplied schema's fields
      Since:
        6.2

    - #### isSupersetOf

          public boolean isSupersetOf(Schema schema)

      Returns true if this schema's fields are a superset of the supplied schema's fields Does not recursively test nested schemas for subsetness.
      Parameters:
        `schema` - the schema against which to compare
      Returns:
        true if this schema's fields are a superset of the supplied schema's fields
      Since:
        6.2

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`
      See Also:
        `Object.hashCode()`

    - #### getDescription

          public String getDescription()

      Returns the description currently set for this Schema. At runtime this method will return `null`, and the description can only be guaranteed to have meaning during application development in the authoring environment.
      Returns:
        this Schema's description String or `null` at runtime

    - #### setDescription

          public void setDescription(String description)

      Sets this schema's description.
      Parameters:
        `description` - the description String for this Schema

    - #### iterator

          public Iterator<Schema.Field> iterator()

      Specified by:
        `iterator` in interface `Iterable<Schema.Field>`
      Returns:
        `Schema.fields()`.iterator()
      Since:
        7.1

    - #### getParentSchemas

          public List<Schema> getParentSchemas()

      Returns:
        a list of the parent Schemas that this Schema inherits from
      Since:
        7.2

    - #### getLocallyDefinedFields

          public Schema getLocallyDefinedFields()

      Returns:
        a Schema representing the subschema of this that is locally defined (i.e. not inherited).
      Since:
        7.2

    - #### getApproximateSize

          public int getApproximateSize()

      Calculates an estimate for the size of a tuple with this schema, including the header and null mask. This is a flat calculation. That is, if you have a variable-sized field (eg., list), the estimate size would assume the list only has one element
      Returns:
        approximate size for a tuple with this schema

Copyright © 2015–2018 Cloud Software Group, Inc.. All rights reserved.