Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Understanding XML Namespaces

As defined in http://www.w3.org/TR/REC-xml-names/, an XML namespace is a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. To promote reusability and modularity, XML document constructs should have universal names, whose scope extends beyond their containing document. XML namespaces are the mechanism which accomplishes this.

XML namespaces are applicable in projects that reference an XML schema: EIS projects that use XML records (see "EIS Projects") and XML projects (see "XML Projects").

This section describes the following:

- TopLink Workbench Namespace Resolution

- Element and Attribute Form Options

- TopLink Runtime Namespace Resolution

## TopLink Workbench Namespace Resolution

Using TopLink Workbench, you can configure the XML schema namespace for your project. For more information, see "Configuring XML Schema Namespace".

## Element and Attribute Form Options

The `xsd:schema` element provides attributes that you can use to specify how elements and attributes should be qualified by namespace.

This section describes the consequences of the following combinations of element and attribute form configuration:

- Element Form Default Qualified and Attribute Form Default Unqualified

- Element and Attribute Form Default Unqualified

- Element and Attribute Form Default Qualified

### Element Form Default Qualified and Attribute Form Default Unqualified

Example 20-5 shows an XML schema in which a target namespace is set. It is coded with `elementFormDefault` set to `qualified` and `attributeFormDefault` set to `unqualified`. This means all elements must be namespace qualified and globally declared attributes must be namespace qualified and locally defined attributes must not be namespace qualified.

Example 20-5 XML Schema with Element Form Default Qualified and Attribute Form Default Unqualified

    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified"
        attributeFormDefault="unqualified"
        xmlns="urn:namespace-example"
        targetNamespace="urn:namespace-example">
        <xsd:element name="customer" type="customer-type"/>
        <xsd:complexType name="customer-type">
            <xsd:sequence>
                <xsd:element name="name" type="xsd:string"/>
                <xsd:element ref="date-of-birth"/>
            </xsd:sequence>
            <xsd:attribute name="id" type="xsd:integer"/>
        </xsd:complexType>
        <xsd:element name="date-of-birth" type="xsd:date"/>
    </xsd:schema>

Example 20-6 shows an XML document that conforms to this XML schema.

Example 20-6 XML Document

    <?xml version="1.0" encoding="UTF-8"?>
    <ns:customer xmlns:ns="urn:namespace-example" id="1">
        <ns:name>Jane Doe</ns:name>
        <ns:date-of-birth>1975-02-21</ns:date-of-birth>
    </ns:customer>

Example 20-7 shows the Java code for a `Customer` class `XMLDescriptor` and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see "Configuring an XML Descriptor" and "Configuring an XML Mapping").

Example 20-7 XML Descriptors and Mappings

    NamespaceResolver namespaceResolver = new NamespaceResolver();
    namespaceResolver.put("ns", "urn:namespace-example");

    XMLDescriptor customerDescriptor = new XMLDescriptor();
    customerDescriptor.setJavaClass(Customer.class);
    customerDescriptor.setDefaultRootElement("ns:customer");
    customerDescriptor.setNamespaceResolver(namespaceResolver);
            XMLDirectMapping idMapping = new XMLDirectMapping();
    idMapping.setAttributeName("id");
    idMapping.setXPath("@id");
    customerDescriptor.addMapping(idMapping);

    XMLDirectMapping nameMapping = new XMLDirectMapping();
    nameMapping.setAttributeName("name");
    nameMapping.setXPath("ns:name/text()");
    customerDescriptor.addMapping(nameMapping);

    XMLDirectMapping birthDateMapping = new XMLDirectMapping();
    birthDateMapping.setAttributeName("birthDate");
    birthDateMapping.setXPath("ns:date-of-birth/text()");
    customerDescriptor.addMapping(birthDateMapping);

### Element and Attribute Form Default Unqualified

Example 20-8 shows an XML schema in which a target namespace is set. It is coded with `elementFormDefault` and `attributeFormDefault` set to `unqualified`. This means that globally defined nodes must be namespace qualified and locally defined nodes must not be namespace qualified.

Example 20-8 XML Schema with Element and Attribute Form Default Unqualified

    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="unqualified"
        attributeFormDefault="unqualified"
        xmlns="urn:namespace-example"
        targetNamespace="urn:namespace-example">
        <xsd:element name="customer" type="customer-type"/>
        <xsd:complexType name="customer-type">
            <xsd:sequence>
                <xsd:element name="name" type="xsd:string"/>
                <xsd:element ref="date-of-birth"/>
            </xsd:sequence>
            <xsd:attribute name="id" type="xsd:integer"/>
        </xsd:complexType>
        <xsd:element name="date-of-birth" type="xsd:date"/>
    </xsd:schema>

Example 20-9 shows an XML document that conforms to this XML schema.

Example 20-9 XML Document

    <?xml version="1.0" encoding="UTF-8"?>
    <ns:customer xmlns:ns="urn:namespace-example" id="1">
        <name>Jane Doe</name>
        <ns:date-of-birth>1975-02-21</ns:date-of-birth>
    </ns:customer>

Example 20-10 shows the Java code for a `Customer` class `XMLDescriptor` and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see "Configuring an XML Descriptor" and "Configuring an XML Mapping").

Example 20-10 XML Descriptors and Mappings

    NamespaceResolver namespaceResolver = new NamespaceResolver();
    namespaceResolver.put("ns", "urn:namespace-example");

    XMLDescriptor customerDescriptor = new XMLDescriptor();
    customerDescriptor.setJavaClass(Customer.class);
    customerDescriptor.setDefaultRootElement("ns:customer");
    customerDescriptor.setNamespaceResolver(namespaceResolver);
                            XMLDirectMapping idMapping = new XMLDirectMapping();
    idMapping.setAttributeName("id");
    idMapping.setXPath("@id");
    customerDescriptor.addMapping(idMapping);

    XMLDirectMapping nameMapping = new XMLDirectMapping();
    nameMapping.setAttributeName("name");
    nameMapping.setXPath("name/text()");
    customerDescriptor.addMapping(nameMapping);

    XMLDirectMapping birthDateMapping = new XMLDirectMapping();
    birthDateMapping.setAttributeName("birthDate");
    birthDateMapping.setXPath("ns:date-of-birth/text()");
    customerDescriptor.addMapping(birthDateMapping);

### Element and Attribute Form Default Qualified

Example 20-11 shows an XML schema in which a target namespace is set. It is coded with `elementFormDefault` and `attributeFormDefault` set to qualified. This means that all nodes must be namespace qualified.

Example 20-11 XML Schema with Element and Attribute Form Default Qualified

    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified"
        attributeFormDefault="qualified"
        xmlns="urn:namespace-example"
        targetNamespace="urn:namespace-example">
        <xsd:element name="customer" type="customer-type"/>
        <xsd:complexType name="customer-type">
            <xsd:sequence>
                <xsd:element name="name" type="xsd:string"/>
                <xsd:element ref="date-of-birth"/>
            </xsd:sequence>
            <xsd:attribute name="id" type="xsd:integer"/>
        </xsd:complexType>
        <xsd:element name="date-of-birth" type="xsd:date"/>
    </xsd:schema>

Example 20-12 shows an XML document that conforms to this XML schema.

Example 20-12 XML Document

    <?xml version="1.0" encoding="UTF-8"?>
    <ns:customer xmlns:ns="urn:namespace-example" ns:id="1">
        <ns:name>Jane Doe</ns:name>
        <ns:date-of-birth>1975-02-21</ns:date-of-birth>
    </ns:customer>

Example 20-13 shows the Java code for a `Customer` class `XMLDescriptor` and XML mappings for its attributes to illustrate how this schema configuration affects the XPaths you specify for default root element and mappings (for more information, see "Configuring an XML Descriptor" and "Configuring an XML Mapping").

Example 20-13 XML Descriptors and Mappings

    NamespaceResolver namespaceResolver = new NamespaceResolver();
    namespaceResolver.put("ns", "urn:namespace-example");

    XMLDescriptor customerDescriptor = new XMLDescriptor();
    customerDescriptor.setJavaClass(Customer.class);
    customerDescriptor.setDefaultRootElement("ns:customer");
    customerDescriptor.setNamespaceResolver(namespaceResolver);
                            XMLDirectMapping idMapping = new XMLDirectMapping();
    idMapping.setAttributeName("id");
    idMapping.setXPath("@ns:id");
    customerDescriptor.addMapping(idMapping);

    XMLDirectMapping nameMapping = new XMLDirectMapping();
    nameMapping.setAttributeName("name");
    nameMapping.setXPath("ns:name/text()");
    customerDescriptor.addMapping(nameMapping);

    XMLDirectMapping birthDateMapping = new XMLDirectMapping();
    birthDateMapping.setAttributeName("birthDate");
    birthDateMapping.setXPath("ns:date-of-birth/text()");
    customerDescriptor.addMapping(birthDateMapping);

## TopLink Runtime Namespace Resolution

It is common for an XML document to include one or more namespaces. TopLink supports this using its `NamespaceResolver`. The namespace resolver maintains pairs of namespace prefixes and Uniform Resource Identifiers (URIs). TopLink uses these prefixes in conjunction with the XPath statements you specify on EIS mappings to XML records and XML mappings.

Although TopLink captures namespace prefixes in the XPath statements for mappings (if applicable), the input document is not required to use the same namespace prefixes. As Example 20-13 shows, TopLink will use the namespace prefixes specified in the mapping when creating new documents.

Figure 20-6 Namespaces in TopLink

Description of "Figure 20-6 Namespaces in TopLink"