XML namespace definitions

XML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules. For example, a customer database and a product inventory database might both define ADI called name that might be used in authorization rules. By defining an XML namespace with the namespace ID item, we can differentiate between the two instances of name by calling the ADI from the product database item:name. This example provides a namespace definition for the item namespace: 

xmlns:item="http://mycompany/namespaces/items
where xmlns is a standard XML attribute name and item is the namespace ID chosen for the namespace. The URI following the = is used to distinguish one namespace ID from another. This namespace declaration associates the namespace ID item with the URI string: 
http://mycompany/namespaces/items

The value of the URI string is of no consequence to the XML and XSL processors but it must be unique. Unlike the XML and XSL processors, the ISAM authorization engine does not permit two namespace IDs to be assigned the same URI value. The ISAM authorization engine uses the URI to uniquely identify the namespaces. Defining two namespaces with the same URI results in an initialization error. The authorization application cannot start, and an error is logged to the error log of the application.

The source from which the item name is to be obtained must be aware of this relationship. The source must be able to make the connection between the item:name requested by the authorization engine and the name data stored in the product database. The source must also be able to provide this data to the authorization engine in an attribute called item:name when it is needed. For example, a dynamic ADI retrieval service must understand that, when it is asked for item:name, it must fetch the required value by looking for name in the product database. The service needs to return the data to the authorization engine in an attribute called item:name. When an application uses namespaces to differentiate or aggregate ADI items, it is required to define the namespace for both the XML and XSL processors. To define a namespace for the XSL processor, add the namespace definition to the xsl-stylesheet-prolog configuration file entry described in input-adi-xml-prolog and xsl-stylesheet-prolog. This example shows how to add a namespace definition for the item namespace to the xsl-stylesheet-prolog entry: 

xsl-stylesheet-prolog = <?xml version='1.0' encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
     xmlns:item="http://mycompany/namespaces/items" version='1.0'>
<xsl:output method = 'text' omit-xml-declaration='yes'
     encoding='UTF-8' indent='no'/>
<xsl:template match='text()'>
</xsl:template>

There are two ways to define a namespace prefix to the XML processor:

In both cases, the namespace declaration must be included in the start tag for the XML element.

The first and simplest method of defining a namespace for the XML processor is to add the namespace definition to the XMLADI document element start tag. Adding the definition to the XMLADI document element start tag is easiest to do because it automatically defines the namespace for the entire document. Any ADI items in the document whose names are prefixed with this namespace ID do not have to have the namespace definition added to their own element start tag.

This method does not suffer any of the drawbacks of defining the namespace using the second method. The [xmladi-attribute-definitions] stanza was added to the configuration file to allow customers to define namespaces globally for use in the XMLADI document. For information about how to add a namespace definition to the [xmladi-attribute-definitions] stanza, see [xmladi-attribute-definitions]. The second method of specifying an XML namespace definition to the XML processor is to add the definition to the XML value of the ADI element. For example, to add the XML namespace definition to the item:name XML item with a string value of Widget A, you would define item:name in XML as follows: 

<item:name xmlns:item="http://mycompany/namespaces/items">
  Widget A
</item:name>

The ADI item:name must be added to an attribute list with the item:name attribute name. Its value is the entire XML element definition in the example entered as a single contiguous text string.

There are some drawbacks to defining the XML namespace in the XML definition of each ADI item rather than defining it globally for the entire XML ADI document. For instance, the value of any ADI items that use a namespace ID prefix must be in XML. The namespace definition can be added only to the XML definition of the value of the item, as demonstrated for item:name in the example. As a result, items of ADI with namespace prefixes cannot have the value 100. The value of the item must be an XML fragment, such as the string <prefix:adi_name>100</prefix:adi_name>.

Any ADI source that can provide values for namespace prefixed ADI items must ensure the appropriate namespace definitions for the item are added to each XML formatted value that it returns. When the service does not normally return XML formatted data and is not aware of namespace prefixes, we must changed it. The change causes an increased processing load for dynamic ADI retrieval services.

By defining the namespace globally, we can avoid all of these complications. If a namespace is not defined for either the XML or XSL processors, an error is logged to the application error logs. The error indicates the namespace ID does not have an associated URI mapping. This problem might occur during the creation of the rule if the XSL processor is not notified of the new namespace. The problem might occur during rule evaluation if the XML processor is not notified.

Parent topic: Authorization rule language