Package com.streambase.sb

Class 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:
    Serialized Form

    • Field Detail

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

      • toString

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

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

      • 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