The Apache Software Foundation > Apache XMLBeans
 

Introduction to Schema Type System

Schema Type Signatures

When you compile schema, the API generated from your schema is integrated with the XMLBeans type system that represents the underlying XML schema. All together, these types make up the schema type system to which your code has access. When handling XML based on the schema, you typically call methods of the API generated when you compiled the schema. However, for the cases when you want to get information about the schema itself, you use the schema type system API.

In the XMLBeans API, you have access to the system itself through SchemaTypeSystem and related classes. These make up a kind of "meta-API," or a view on the schema. You can use the schema type system API to discover the type system at run time. See the reference topic on that interface for an overview of the schema type system.

A schema is made up of schema components. Schema components are the pieces of a schema, such as a type definition, an element declaration, attribute declaration, and so on. To mirror these in the schema type system, a SchemaComponent instance represents a component in the underlying schema; separate components have corresponding types. For example you would have a SchemaType object for a CustomerType your schema defined, or a SchemaGlobalElement object for a global PurchaseOrder element. You would also have a SchemaType for built-in schema types, such as xs:string or xs:datetime. XMLBean provides a "signature" to describe each type. You can retrieve this signature by calling the SchemaType class's toString method.

The toString method returns XMLBeans' version of a unique signature for a schema type. This string is useful for debugging because it describes a given type even when the type doesn't have a name.

Note: It's important to remember that this signature is an XMLBeans convention, rather than a standard from the schema working group. The working group has not yet standardized a signature for XML schema types. As a result the signature you'll see from XMLBeans is subject to change — whatever the schema working group comes up with in the end (if anything) is probably what will be used by this API. In other words, don't write a program to decode the signature.

You can use the following description to understand how a signature is constructed.

  • Global types. If the type has a name, it's a global type. The following form is used:

    T=<localname>@<targetNamespace>

    The "T" is for "type," of course. "localname" is a convention used by qnames (qualified names), which include a local name and the namespace URI (if any). So an example might be:

    T=customer@openuri.org
  • Document types and global attribute types. These correspond to a special anonymous type containing one global element or attribute. These special types are generated by XMLBeans to represent global types declared with the <element> or <attribute> tag in schema. Because such types are types, but are declared as elements or attributes, they require special treatment. The following signature form is used:

    D=<document-element-name>@<targetNamespace>
    R=<attribute-type-name>@<targetNamespace>

    Note that these are also the signatures of a type returned by a FooDocument.type or FooAttribute.type method call.

  • Anonymous types. If the type is anonymous, it is defined as an element or attribute, or within a further anonymous type. In this case, the signature is built by establishing the local context (in order words, what is the anonymous type nested in?). From the local context, the larger context is built recursively. In other words, the signature is built by giving not only the anonymous type itself, but also by describing its context.

    The following rules are used for building a signature for an anonymous type.

    • It might be an anonymous type defined inside a local element or attribute, which in turn is defined within something else:

      If the element is form="qualified" (the usual default):

    Note
    E=<eltname>|<signature of the type within which the elt is defined>
    If the element is form="unqualified":
    U=<eltname>|<signature of the type within which the elt is defined> If the attribute is form="unqualified" (the usual default):
    A=<attrname>|<signature of the type within the attr is defined> if the attribute is form="qualified":
    Q=<attrname>|<signature of the type within the attr is defined>
  • It might be an anonymous type defined a simple restriction, union, or list definition:
    Note
    M=#|<signature of the containing union type> (The # is a number indicating which union member it is, by source order — such as 0,1,2, etc.)
    B=|<signature of the containing base type for a restriction>
    I=|<signature of the containing list type>
    • In the future if anonymous types are allowed in some other context, there may be more codes.

An Example

So, for example, if you have a type that describes the list items within an attribute of an instance that looks like this:

<root mylist="432 999 143 123">

The schema, if done with lots of nested types, could look something like this:

<schema targetNamespace="myNamespace" elementFormDefault="qualified">
<element name="root">
<complexType>
<attribute name="mylist">
<simpleType>
<list>
<simpleType>
<!--This is the type that the signature is for -->
<restriction base="xs:nonNegativeInteger">
<totalDigits value="3"/>..

The signature for the simpleType indicated in the example would be:

I=|A=mylist|E=root|D=root@myNamespace

You could read this as:

"The type of the list item | within the type of the mylist attribute's type | within the type of the root element | within the document type for <root> documents | in the myNamespace namespace".

Note that the signature structure mirrors the Java class structure generated by XMLBeans when compiling the schema. In other words, if you were to compile a schema that included the preceding snippet, you would be able to access an instance of the schema with Java code like the following:

SchemaType sType = RootDocument.Root.MyList.Item.type;

Related Topics