Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Handling namespaces

> There are three kinds of namespaces:

> - A local namespace, which is one that is declared in that tag.

> - An inherited namespace, which is one specified in an ancestor tag. For example, a namespace declared by the root node can be used in the entire document.

> - The default namespace, which is an unspecified namespace (no prefix provided).

> There are two ways for a namespace to be created when writing an XML document. They can be created implicitly when starting an element or they can be declared explicitly after a tag has been started. Implicit namespaces are created with the methods `START-ELEMENT`, `WRITE-EMPTY-ELEMENT`, and `WRITE-DATA-ELEMENT`. Explicit namespaces are created with the methods `DECLARE-NAMESPACE` or `INSERT-ATTRIBUTE`.

> Table 21–2: Namespace variations
> Method call example/ Resulting tag | Use case explanation
> --- | ---
>     START-ELEMENT("name", "")
>     <name>
> | Case: You supply an element `name`, but no namespace prefix and no namespace URI. Result: The element is written without a prefix and the default namespace will be used.
>     START-ELEMENT("prefix:name", "")
>     <prefix:name>
> | Case 1: You supply an element `name` with a namespace `prefix`, but no namespace URI. The supplied prefix has been previously associated with a namespace URI. Result: The element is written with the supplied `prefix` and the previously associated namespace URI will be used.
>     START-ELEMENT("prefix:name", "")
>     error
> | Case 2: You supply an element `name` with a namespace `prefix`, but no namespace URI. The supplied prefix has not been previously associated with a namespace URI. The `STRICT` attribute is set to `TRUE`. Result: The call generates an error. Only the default namespace can be set to an empty string (““).
>     START-ELEMENT("prefix:name", "")
>     <prefix:name xmlns:prefix="">
> | Case 3: You supply an element `name` with a namespace `prefix`, but no namespace URI. The supplied prefix has not been previously associated with a namespace URI. The `STRICT` attribute is set to `FALSE`. Result: The element is written with the supplied `prefix` and an empty namespace is specified.
>     START-ELEMENT("name", "namespaceUri")
>     <prefix:name>
> | Case 1: You supply an element `name` without a namespace prefix. You supply a `namespaceUri` that has been previously associated with a namespace prefix. Result: The element is written using the previously associated prefix and the declared namespace URI is used.
>     START-ELEMENT("name", "namespaceUri")
>     <name xmlns="namespaceUri">
> | Case 2: You supply an element `name` without a namespace prefix. You supply a `namespaceUri` that has not been previously associated with a namespace prefix. Result: The element is written without a prefix and the `namespaceUri` is set to the namespace URI associated with the default namespace.
>     START-ELEMENT("prefix:name",
>     "namespaceUri")
>     <prefix:name>
> | Case 1: You supply an element `name` with a namespace `prefix` and a `namespaceUri` that has been previously associated with the supplied prefix. Result: The element is written with the supplied prefix and name and the previously associated namespace URI will be used. Since the namespace matching the supplied prefix and URI pair has already been declared, it will not be redeclared.
>     START-ELEMENT("prefix:name",
>     "namespaceUri")
>     <prefix:name
>     xmlns:prefix="namespaceUri">
> | Case 2: You supply an element `name` with a namespace `prefix` and a `namespaceUri.` Either one or both of the namespace prefix and the namespace URI has already been used in a previous declaration, but the pair have not been declared together. Result: The element is written with the supplied `prefix` and `name` and `namespaceUri` declared. This amounts to the declaration of a new namespace.
>     START-ELEMENT("prefix:name",
>     "namespaceUri")
>     error
> | Case 3: You supply an element `name` with a namespace `prefix` and a `namespaceUri.` The namespace prefix matches the prefix used in the element, but the URIs do not match. The `STRICT` attribute is set to `TRUE`. Result: The method call generates an error message. Within an element, namespaces are like attributes and must be unique. Exception: In the case where the element’s URI is the empty string, the tag will be written with the supplied `namespaceUri`.
>     START-ELEMENT("prefix:name",
>     "namespaceUri")
>     <prefix:name
>     xmlns:prefix="namespaceUri"
>     xmlns:prefix="">
> | Case 4: You supply an element `name` with a namespace `prefix` and a `namespaceUri.` The namespace prefix matches the prefix used in the element, but the URIs do not match. The `STRICT` attribute is set to `FALSE`. Result: The tag will be written, but it will not be valid XML.
>     DECLARE-NAMESPACE("namespaceUri",
>     "prefix")
>     <qname xmlns:prefix="namespaceUri">
> | Case 1: You supply a new prefix and new namespaceUri that do not overlap with those declared in the element. Result: Creates the expected namespace without error.
>     DECLARE-NAMESPACE("namespaceUri",
>     "prefix")
>     <prefix:name
>     xmlns:prefix="namespaceUri">
> | Case 2: The provided `namespaceUri` matches the namespace URI declared in the element and `prefix` matches the namespace prefix declared in the element. Result: Re-declaring an implicitly created namespace (the namespace declared in the element) does no harm and will not generate an error message.
>     DECLARE-NAMESPACE("namespaceUri",
>     "prefix")
>     <prefix:name
>     xmlns:prefix="namespaceUri">
> | Case 3: `namespaceUri` is provided and the namespace URI declared in the element is the empty string (““), and the provided `prefix` matches the namespace prefix declared in the element. Result: The namespace is created without error. In other words, if you are going to explicitly create your namespaces, you do not need to provide the namespace URI when you create the element.
>     DECLARE-NAMESPACE("namespaceUri",
>     "prefix")
>     error
> | Case 4: `namespaceUri` is provided but it does not match the namespace URI declared in the element and the supplied `prefix` does match the namespace prefix declared in the element. The `STRICT` attribute is set to `TRUE`. Result: The method call generates an error. Within an element, namespaces are like attributes and must be unique.
>     DECLARE-NAMESPACE("namespaceUri",
>     "").
>     <qname xmlns="namespaceUri">
> | Case 1: You provide only a `namespaceUri` and an empty string (““) as the namespace prefix. Result: You create the default namespace.
>     DECLARE-NAMESPACE("namespaceUri",
>     "").
>     error
> | Case 2: The element has declared a default namespace with a different namespace URI than the one you provide with `namespaceUri.` The `STRICT` attribute is set to `TRUE`. Result: The method call generates an error. Within an element, namespaces are like attributes and must be unique.
>     DECLARE-NAMESPACE("namespaceUri",
>     "").
>     <name xmlns="namepsaceUri"
>     xmlns="namespaceUri">
> | Case 3: The element has declared a default namespace with a different namespace URI than the one you provide with `namespaceUri.` The `STRICT` attribute is set to `FALSE`. Result: The tag will be written, but it will not be valid XML.
>     DECLARE-NAMESPACE("", "prefix")
>     error
> | Case 1: You provide an empty string (““) as the namespace URI and supply the `prefix`. The `STRICT` attribute is set to `TRUE`. Result: The method call generates an error. Only the default namespace can be declared as the empty string (““).
>     DECLARE-NAMESPACE("", "prefix")
>     <qname xmlns:prefix="">
> | Case 2: You provide an empty string (““) as the namespace URI and supply a `prefix` that matches the namespace prefix declared in the element. The `STRICT` attribute is set to `FALSE`. Result: This can be useful when not running in `STRICT` mode to reset the element namespace prefix to the empty string (““).
>     DECLARE-NAMESPACE("", "prefix").
>     <prefix:name
>     xmlns:prefix="namepsaceUri"
>     xmlns:prefix="">
> | Case 3: You provide an empty string (““) as the namespace URI and supply a `prefix`. The `STRICT` attribute is set to `FALSE`. Result: The tag will be written, but it will not be valid XML.
>     DECLARE-NAMESPACE("", "").
>     <qname xmlns="">
> | Case 1: You provide an empty string (““) as the namespace URI and as the namespace prefix. Result: You create the default namespace as empty.
>     DECLARE-NAMESPACE("", "").
>     error
> | Case 2: The element has declared a specific default namespace and you provide `namespaceUri` which is the empty string (““). The `STRICT` attribute is set to `TRUE`. Result: The method call generates an error. Within an element, namespaces are like attributes and must be unique.
>     DECLARE-NAMESPACE("", "").
>     <name xmlns="namespaceUri" xmlns="">
> | Case 3: The element has declared a specific default namespace and you provide `namespaceUri` which is the empty string (““). The `STRICT` attribute is set to `FALSE`. Result: The tag will be written, but it will not be valid XML

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095