Use sequence types

Use sequence types when declaring variables for the return or parameter types of functions.

In the XML API, sequence types are represented using XSequenceType objects. XSequenceType objects can represent the same set of sequence types as the SequenceType syntax defined in XPath 2.0. XSequenceType objects are created through the XSequenceTypeFactory interface. You can obtain an instance of XSequenceTypeFactory using the getSequenceTypeFactory() method on an XFactory instance.

Tasks

• XSequenceTypeFactory has several methods for creating XSequenceType instances.

  Each method on the XSequenceTypeFactory interface has an XSequenceType.OccurrenceIndicator parameter except for emptySequence(). OccurrenceIndicator is an enum that represents the cardinality of the sequence; ZERO_OR_ONE corresponds to "?" in SequenceType syntax, ZERO_OR_MORE to "*", ONE_OR_MORE to "+", and ONE to no occurrence indicator for sequences of exactly one item.

• The XSequenceTypeFactory interface methods use QNames to refer to the names of nodes such as elements and attributes, and also to types and global element and attribute declarations.

  QNames representing types must refer to built-in types or to types defined in schemas that have been registered with the same XFactory instance used to obtain the XSequenceTypeFactory instance. Similarly, QNames representing global element or attribute declarations must refer to global declarations present in schemas that have been registered with the same XFactory instance.

Example

Method Signature	Example Sequence Types	Comments
emptySequence()	empty-sequence()
item(OccurrenceIndicator cardinality)	item()*
atomic(QName typeName, OccurrenceIndicator cardinality)	xs:integer	"sc:type" is a QName referring to a user-defined schema type.
sc:type+
documentNode(OccurrenceIndicator cardinality)	document-node()?
documentNodeWithElement(QName elementNameOrWildcard, QName typeName, boolean nillable, OccurrenceIndicator cardinality)	document-node(element())	"ns:elem" is a QName representing an element name, and "sc:type" is a QName referring to a user-defined schema type. The elementNameOrWildcard and typeName parameters are optional; use null if the element name or type does not matter.
document-node(element(ns:elem))?
document-node(element(*, sc:type?))
documentNodeWithSchemaElement(QName elementName, OccurrenceIndicator cardinality)	document-node(schema-element(sc:elemDecl))	"sc:elemDecl" is a QName referring to a global element declaration in a schema.
element(QName elementNameOrWildcard, QName typeName, boolean nillable, OccurrenceIndicator cardinality)	element(*)	"ns:elem" is a QName representing an element name, and "sc:type" is a QName referring to a user-defined schema type. The elementNameOrWildcard and typeName parameters are optional; use null if the element name or type does not matter.
element(ns:elem, sc:type)*
attribute(QName attributeNameOrWildcard, QName typeName, OccurrenceIndicator cardinality)	attribute()+	"ns:attrib" is a QName representing an attribute name. The attributeNameOrWildcard and typeName parameters are optional; use null if the attribute name or type does not matter.
attribute(ns:attrib)
attribute(ns:attrib, xs:string)?
schemaElement(QName elementName, OccurrenceIndicator cardinality)	schema-element(sc:elemDecl)*	"sc:elemDecl" is a QName referring to a global element declaration in a schema.
schemaAttribute(QName attributeName, OccurrenceIndicator cardinality)	schema-attribute(sc:attribDecl)	"sc:attribDecl" is a QName referring to a global attribute declaration in a schema.
processingInstruction(QName piNCName, OccurrenceIndicator cardinality)	processing-instruction()?	"pinst" is an NCName representing the name of a processing instruction.
processing-instruction("pinst")
processing-instruction(pinst)
comment(OccurrenceIndicator cardinality)	comment()
text(OccurrenceIndicator cardinality)	text()+
node(OccurrenceIndicator cardinality)	node()*

The following example shows how to create XSequenceType objects to represent various sequence types. Some of the results refer to types and declarations from a schema. The example assumes that the schema is available through the schemaSource source object.

// Create the factory
XFactory factory = XFactory.newInstance();

// Obtain an XSeqeuenceTypeFactory instance
XSequenceTypeFactory stFactory = factory.getSequenceTypeFactory();

// Create a sequence type for a sequence of xs:integer values: "xs:integer*"
XSequenceType integerSequenceType = stFactory.atomic(
        XTypeConstants.INTEGER_QNAME,
        XSequenceType.OccurrenceIndicator.ZERO_OR_MORE);

// Create a sequence type for a single node: "node()"
XSequenceType nodeType = stFactory.node(OccurrenceIndicator.ONE);

// Define a constant for the target namespace of a schema containing user-defined types and declarations
final String targetNamespace = "http://www.example.org/schema/";

// Register the schema with the XFactory
factory.registerSchema(schemaSource);

// Create a sequence type for exactly one document node with an element of type "employeeRecord" from the schema:
// "document-node(element(*, ns:employeeRecord))"
XSequenceType employeeRecordDocumentType = stFactory.documentNodeWithElement(
        null,
        new QName(targetNamespace, "employeeRecord"),
        false,
        XSequenceType.OccurrenceIndicator.ONE);

// Create a sequence type for an optional attribute matching the attribute declaration "type" in the schema:
// "schema-attribute(ns:type)?"
XSequenceType optionalEmployeeType = stFactory.schemaAttribute(
        new QName(targetNamespace, "type"),
        XSequenceType.OccurrenceIndicator.ZERO_OR_ONE);

// Create a sequence type for one or more atomic values of type "telephoneNumber" from the schema:
// "ns:telephoneNumber+"
XSequenceType telephoneNumbersType = stFactory.atomic(
        new QName(targetNamespace, "telephoneNumber"),
        XSequenceType.OccurrenceIndicator.ONE_OR_MORE);

Contents of sample schema:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:ns="http://www.example.org/schema/" targetNamespace="http://www.example.org/schema/">
    <complexType name="employeeRecord">
        <sequence>
            <element name="name" type="string"></element>
            <element name="id" type="int"></element>
            <element name="telephone" type="ns:telephoneNumber"></element>
        </sequence>
        <attribute ref="ns:type"></attribute>
    </complexType>

    <simpleType name="telephoneNumber">
        <restriction base="string">
            <pattern value="\d{3}-\d{3}-\d{4}"></pattern>
        </restriction>
    </simpleType>

    <element name="employee" type="ns:employeeRecord"></element>

    <simpleType name="employeeType">
        <restriction base="string">
            <enumeration value="full-time"></enumeration>
            <enumeration value="part-time"></enumeration>
            <enumeration value="seasonal"></enumeration>
        </restriction>
    </simpleType>

    <attribute name="type" type="ns:employeeType"></attribute>
</schema>

Related:

The XFactory class

SequenceType syntax

XPath 2.0