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:

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.

Field Summary

Fields

Modifier and Type	Field and Description
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

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.
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.
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.
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

Field Detail

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

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:

name - 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

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.

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

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

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

Throws:

TupleException - if the number of fields is incorrect, or a conversion error occurs

See Also:

for more info

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 elememt

Returns: