public class Schema extends java.lang.Object implements java.io.Serializable, java.lang.Iterable<Schema.Field>
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.
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.Modifier and Type | Class and Description |
---|---|
static class |
Schema.Field
Information (name, type, and optionally size) about a field in a Schema.
|
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 and Description |
---|
Schema(org.w3c.dom.Element element)
Construct a Schema from an XMLElement
|
Schema(Schema baseSchema)
Construct a Schema from another schema
|
Schema(java.lang.String xmlSchema)
Construct a Schema out of XML represented as a String
|
Schema(java.lang.String name,
java.util.List<Schema.Field> fields)
Create a new schema from a list of
Schema.Field |
Schema(java.lang.String name,
Schema.Field... fields)
Construct a Schema out of a list of
Schema.Field |
Schema(java.lang.String name,
Schema baseSchema)
Construct a Schema with a new name from another schema
|
Schema(java.lang.String name,
java.lang.String description,
Schema.Field... fields)
Construct a Schema out of a list of
Schema.Field |
Modifier and Type | Method and Description |
---|---|
static Schema.Field |
createField(DataType type,
java.lang.String name)
Creates a new Field of the given DataType, with the given name.
|
static Schema.Field |
createFunctionField(java.lang.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(java.lang.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(java.util.List<java.lang.String> fieldValues,
int offset,
int length)
Create a Tuple with this schema from the supplied collection of strings
|
Tuple |
createTuple(java.util.List<java.lang.String> fieldValues,
int offset,
int length,
java.lang.String nullString)
Create a Tuple with this schema from the supplied collection of strings
|
Tuple |
createTuple(java.lang.String... fieldValues)
Create a Tuple with this schema from the supplied collection of strings
|
Tuple |
createTuple(java.lang.String[] fieldValues,
int offset,
int length)
Create a Tuple with this schema from the supplied collection of strings
|
Tuple |
createTuple(java.lang.String[] fieldValues,
int offset,
int length,
java.lang.String nullString)
Create a Tuple with this schema from the supplied collection of strings
|
static Schema.Field |
createTupleField(java.lang.String name,
Schema schema)
Creates a new Field of type TUPLE, with the given name and given schema
|
boolean |
equals(java.lang.Object obj)
Return true if the supplied schema is the same as this schema.
|
boolean |
equalsNoCapture(Schema scm) |
java.util.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.
|
java.lang.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(java.lang.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(java.lang.CharSequence fieldName)
Return the index within the Schema of the Field with the given name
|
int |
getFieldIndex(java.lang.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() |
java.lang.String |
getName()
Return the name of the Schema or null at runtime.
|
java.util.List<Schema> |
getParentSchemas() |
boolean |
hasField(java.lang.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.
|
java.util.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(java.lang.String description)
Sets this schema's description.
|
org.w3c.dom.Element |
toElement(org.w3c.dom.Document document)
Create an XML document representation of this Schema
|
org.w3c.dom.Element |
toElement(org.w3c.dom.Document document,
boolean addUUID)
Create an XML document representation of this Schema
|
java.lang.String |
toHumanString()
Return a description of the Schema in using a SSQL style format
|
java.lang.String |
toSsqlStyleString()
Deprecated.
|
java.lang.String |
toString()
Return the name of the schema
|
java.lang.String |
toStringWithFields()
Deprecated.
|
public static final boolean ALLOW_TUPLE_FIELD_SAME_NAME
public static final Schema EMPTY_SCHEMA
public static final int NO_SUCH_FIELD
public Schema(java.lang.String name, java.util.List<Schema.Field> fields)
Schema.Field
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.java.lang.IllegalArgumentException
- if the schema name is invalidpublic Schema(org.w3c.dom.Element element) throws XmlInterpretationException
element
- The Element to start fromXmlInterpretationException
- thrown when unable to create a Schema object from the XML Elementjava.lang.IllegalArgumentException
- if the schema name is invalidpublic Schema(java.lang.String xmlSchema) throws StreamBaseException
xmlSchema
- The String representation of the string in XMLStreamBaseException
- thrown when unable to parse xmlSchema
as an XML documentXmlInterpretationException
- thrown when unable to create a Schema object from the XML Elementjava.lang.IllegalArgumentException
- if the schema name is invalidpublic Schema(java.lang.String name, Schema.Field... fields)
Schema.Field
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.java.lang.IllegalArgumentException
- if the schema name is invalidpublic Schema(java.lang.String name, java.lang.String description, Schema.Field... fields)
Schema.Field
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 hasfields
- an array of 0 or more fields. Must not be null.java.lang.IllegalArgumentException
- if the schema name is invalidpublic Schema(java.lang.String name, Schema baseSchema)
name
- the name of this new schema, generally null. See the class-level documentation
for Schema
for details.baseSchema
- the base schemajava.lang.IllegalArgumentException
- if the schema name is invalidpublic Schema(Schema baseSchema)
baseSchema
- the base schemapublic static final Schema getErrorSchema()
public static Schema.Field createField(DataType type, java.lang.String name)
type
- the DataType for the new fieldname
- the new field's namecreateField(DataType, String, int)
public static Schema.Field createListField(java.lang.String name, CompleteDataType elementType)
name
- the new field's nameelementType
- the list's element typepublic static Schema.Field createTupleField(java.lang.String name, Schema schema)
name
- the new field's nameschema
- the tuple's schemapublic static Schema.Field createFunctionField(java.lang.String fieldName, Schema argumentSchema, CompleteDataType returnType)
fieldName
- the new field's nameargumentSchema
- the function's argumentsreturnType
- the function's return typepublic Schema.Field getField(int fieldIndex)
fieldIndex
- The index of the Fieldpublic Schema.Field getField(java.lang.String fieldPathName) throws TupleException
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.TupleException
- thrown when the Field cannot be foundpublic java.util.List<Schema.Field> fields()
public Schema.Field[] getFields()
public DataType[] getFieldTypes()
public int getFieldCount()
public int getFieldIndex(java.lang.CharSequence fieldName)
fieldName
- The name (note: not path name) of the Field to search forpublic int getFieldIndex(java.lang.String fieldName)
fieldName
- The name (note: not path name) of the Field to search forpublic boolean hasField(java.lang.CharSequence fieldPathName)
fieldPathName
- The path name of the Field to search forpublic boolean sameFieldTypes(Schema other)
other
- the schema to compare topublic boolean sameFieldsAs(Schema other)
other
- the schema to compare topublic java.lang.String getName()
public byte[] getHash()
public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String toStringWithFields()
Schema.toHumanString()
public java.lang.String toHumanString()
public java.lang.String toSsqlStyleString()
Schema.toHumanString()
public org.w3c.dom.Element toElement(org.w3c.dom.Document document)
document
- The Document that the XML Document will belong to.public org.w3c.dom.Element toElement(org.w3c.dom.Document document, boolean addUUID)
document
- The Document that the XML Document will belong to.addUUID
- add the UUID to the output xmlpublic Tuple createTuple()
public Tuple createTuple(java.lang.String... fieldValues) throws TupleException
fieldValues
- the field values to set the tuple toTupleException
- if the number of fields is incorrect, or a conversion error occursfor more info
public Tuple createTuple(java.lang.String[] fieldValues, int offset, int length) throws TupleException
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
fieldValues
- the field values to set the tuple tooffset
- offset into fieldValues listlength
- number of values to copy into tuple must be same as number of fields in this SchemaTupleException
- if the number of fields is incorrect, or a conversion error occurspublic Tuple createTuple(java.lang.String[] fieldValues, int offset, int length, java.lang.String nullString) throws TupleException
fieldValues
- the field values to set the tuple tooffset
- offset into fieldValues listlength
- number of values to copy into tuple must be same as number of fields in this SchemanullString
- a string to consider as null if it is encountered as a value;
use null to never consider field values to be nullTupleException
- if the number of fields is incorrect, or a conversion error occursfor more info
public Tuple createTuple(java.util.List<java.lang.String> fieldValues, int offset, int length) throws TupleException
fieldValues
- the field values to set the tuple tooffset
- offset into fieldValues listlength
- number of values to copy into tuple must be same as number of fields in this SchemaTupleException
- if the number of fields is incorrect, or a conversion error occursfor more info
public Tuple createTuple(java.util.List<java.lang.String> fieldValues, int offset, int length, java.lang.String nullString) throws TupleException
fieldValues
- the field values to set the tuple tooffset
- offset into fieldValues listlength
- number of values to copy into tuple must be same as number of fields in this SchemanullString
- a string to consider as null if it is encountered as a value;
use null to never consider field values to be nullTupleException
- if the number of fields is incorrect, or a conversion error occursfor more info
public boolean equalsNoCapture(Schema scm)
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
obj
- the schema to compare this schema topublic boolean isSubsetOf(Schema schema)
schema
- the schema against which to comparepublic boolean isSupersetOf(Schema schema)
schema
- the schema against which to comparepublic int hashCode()
hashCode
in class java.lang.Object
Object.hashCode()
public java.lang.String getDescription()
null
, and the description can only be guaranteed
to have meaning during application development in the authoring environment.null
at runtimepublic void setDescription(java.lang.String description)
description
- the description String for this Schemapublic java.util.Iterator<Schema.Field> iterator()
iterator
in interface java.lang.Iterable<Schema.Field>
Schema.fields()
.iterator()public java.util.List<Schema> getParentSchemas()
public Schema getLocallyDefinedFields()
public int getApproximateSize()