Package 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.Fields, 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:

  • Field Details

    • ALLOW_TUPLE_FIELD_SAME_NAME

      public static final boolean ALLOW_TUPLE_FIELD_SAME_NAME
      Allow tuple field to be the same as the schema field 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:

  • Constructor Details

    • 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 Details

    • getErrorSchema

      public static 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:

    • 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

    • toHex

      public static String toHex(byte[] buffer, int fromPos)
      Convert a byte buffer to hex
      Parameters:
      buffer - The buffer to dump
      fromPos - The offset to begin the dump on
      Returns:
      The converted buffer

    • toHex

      public static String toHex(byte[] buffer, int fromPos, int maxLen)
      Convert a byte buffer to hex
      Parameters:
      buffer - The buffer to dump
      fromPos - The offset to begin the dump on
      maxLen - The max length to dump
      Returns:
      The converted buffer

    • 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 - Tuple class associated with this schema
      info - Tuple class information

    • toString

      public String toString()
      Return the name of the schema
      Overrides:
      toString in class Object
      Returns:
      the name of the schema

    • toStringWithFields

      @Deprecated public String toStringWithFields()
      Deprecated.
      Use toHumanString() instead
      Return a String representation of this Schema
      Returns:
      String representation of this Schema
      See Also:

    • toMultiLineHumanString

      public String toMultiLineHumanString()
      Returns:
      A description of the schema in a multiline format, with fields alphabetically sorted

    • toMultiLineHumanStringSchemaOrder

      public String toMultiLineHumanStringSchemaOrder()
      Returns:
      A description of the schema in a multiline format, with fields in the schema order

    • 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

      @Deprecated public String toSsqlStyleString()
      Deprecated.
      StreamSQL is 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:

    • 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

    • getTupleRepLayout

      public final TupleRep.TupleLayout getTupleRepLayout()
      Returns:
      The tuple representation layout

    • 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:

    • 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
      Returns:
      New tuple
      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
      Returns:
      New tuple
      Throws:
      TupleException - if the number of fields is incorrect, or a conversion error occurs
      See Also:

    • 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:

    • 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:

    • equalsNoCapture

      public boolean equalsNoCapture(Schema scm)
      Compare schemas without capture fields
      Parameters:
      scm - Compare with this schema
      Returns:
      true if equal

    • 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

    • 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:
      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